> ## Documentation Index > Fetch the complete documentation index at: https://sambanova-systems.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create completion ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/sambanova/openapi.documented.yml post /completions openapi: 3.1.1 info: title: SambaNova cloud API description: SambaNova cloud API Specification version: 1.2.0 termsOfService: https://sambanova.ai/cloud-end-user-license-agreement contact: email: info@sambanova.ai name: SambaNova information license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.sambanova.ai/v1 security: - api_key: [] externalDocs: description: Find out more in the official SambaNova docs url: https://docs.sambanova.ai/docs/en/api-reference/overview paths: /completions: post: tags: - Completions summary: Create completion operationId: createCompletion requestBody: content: application/json: schema: $ref: '#/components/schemas/CompletionRequest' description: text prompt and parameters required: true responses: '200': description: Successful Response content: application/json: schema: oneOf: - $ref: '#/components/schemas/CompletionResponse' - $ref: '#/components/schemas/CompletionStreamResponse' '400': description: Bad Request - Missing or invalid parameters content: text/plain: schema: type: string example: 'Invalid request body: - missing property ''model''"' application/json: schema: oneOf: - $ref: '#/components/schemas/GeneralError' - $ref: '#/components/schemas/SimpleError' examples: missing_model: summary: No model parameter provided value: error: message: you must provide a model parameter type: invalid_request_error param: null code: null request_id: a4fa849e invalid_json: summary: Malformed JSON body value: error: code: null message: >- We could not parse the JSON body of your request. (HINT: This likely means you aren't using your HTTP library correctly. A JSON payload is expected, but what was sent was not valid JSON.) param: null type: invalid_request_error request_id: 3f7db127 simple: summary: Simple error (unhandled cases) value: error: Model name is required '401': description: Unauthorized access content: application/json: schema: $ref: '#/components/schemas/GeneralError' examples: invalid_api_key: summary: Invalid API key provided value: error: message: >- Incorrect API key provided: *****. You can find your API key at https://cloud.sambanova.ai/apis. type: invalid_request_error param: null code: invalid_api_key request_id: d79vcq57os633dverhi0 missing_api_key: summary: No API key provided value: error: message: >- You didn't provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer YOUR_KEY). type: invalid_request_error param: null code: null request_id: d7a0dct7os633dvesi60 '404': description: Not found - model does not exist or wrong endpoint called content: application/json: schema: oneOf: - $ref: '#/components/schemas/GeneralError' - $ref: '#/components/schemas/SimpleError' examples: model_not_found: summary: Model does not exist or is not accessible value: error: code: model_not_found message: >- The model `abc` does not exist or you do not have access to it. param: model type: invalid_request_error request_id: 887a8227 simple: summary: Simple error (unhandled cases e.g. wrong endpoint) value: error: Not found '408': description: Request timeout content: application/json: schema: $ref: '#/components/schemas/SimpleError' '410': description: Gone - model is no longer available (deprecated or removed) content: application/json: schema: $ref: '#/components/schemas/SimpleError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/GeneralError' '500': description: Internal Server Error. Unexpected issue on server side. content: text/plain: schema: type: string '503': description: Service Temporarily Unavailable content: text/plain: schema: type: string example: Service Temporarily Unavailable security: - api_key: [] x-codeSamples: - lang: JavaScript source: |- import SambaNova from 'sambanova'; const client = new SambaNova({ apiKey: process.env['SAMBANOVA_API_KEY'], // This is the default and can be omitted }); const completion = await client.completions.create({ model: 'gpt-oss-120b', prompt: '<|begin_of_text|><|start_header_id|>system<|end_header_id|> You are a helpful assistant.<|eot_id|><|start_header_id|>user<|end_header_id|> create a poem using palindromes<|eot_id|><|start_header_id|>assistant<|end_header_id|>', }); console.log(completion); - lang: Python source: |- import os from sambanova import SambaNova client = SambaNova( api_key=os.environ.get("SAMBANOVA_API_KEY"), # This is the default and can be omitted ) for completion in client.completions.create( model="gpt-oss-120b", prompt="<|begin_of_text|><|start_header_id|>system<|end_header_id|> You are a helpful assistant.<|eot_id|><|start_header_id|>user<|end_header_id|> create a poem using palindromes<|eot_id|><|start_header_id|>assistant<|end_header_id|>", ): print(completion) components: schemas: CompletionRequest: title: Completion Request type: object description: completions request object additionalProperties: true properties: model: title: Model description: >- The model ID to use (e.g. gpt-oss-120b). See available [models](https://docs.sambanova.ai/docs/en/models/sambacloud-models) anyOf: - type: string - enum: - Meta-Llama-3.3-70B-Instruct - Meta-Llama-3.2-1B-Instruct - Meta-Llama-3.2-3B-Instruct - Llama-3.2-11B-Vision-Instruct - Llama-3.2-90B-Vision-Instruct - Meta-Llama-3.1-8B-Instruct - Meta-Llama-3.1-70B-Instruct - Meta-Llama-3.1-405B-Instruct - Qwen2.5-Coder-32B-Instruct - Qwen2.5-72B-Instruct - QwQ-32B-Preview - Meta-Llama-Guard-3-8B - DeepSeek-R1 - DeepSeek-R1-0528 - DeepSeek-V3-0324 - DeepSeek-V3.1 - DeepSeek-V3.1-cb - DeepSeek-V3.1-Terminus - DeepSeek-V3.2 - DeepSeek-R1-Distill-Llama-70B - Llama-4-Maverick-17B-128E-Instruct - Llama-4-Scout-17B-16E-Instruct - Qwen3-32B - Qwen3-235B - Llama-3.3-Swallow-70B-Instruct-v0.4 - gpt-oss-120b - ALLaM-7B-Instruct-preview - MiniMax-M2.5 - MiniMax-M2.7 - gemma-3-12b-it prompt: title: Prompt type: string description: Prompt to send to the model. examples: - > <|begin_of_text|><|start_header_id|>system<|end_header_id|> You are a helpful assistant.<|eot_id|><|start_header_id|>user<|end_header_id|> create a poem using palindromes<|eot_id|><|start_header_id|>assistant<|end_header_id|> max_tokens: title: Max Tokens type: integer description: >- The maximum number of tokens that can be generated in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. nullable: true example: 2048 max_completion_tokens: title: Max Completion Tokens type: integer description: >- The maximum number of tokens that can be generated in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. nullable: true example: 2048 temperature: title: Temperature type: number description: >- What sampling temperature to use, determines the degree of randomness in the response. between 0 and 2, Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. Is recommended altering this, top_p or top_k but not more than one of these. minimum: 0 maximum: 2 default: 0.7 nullable: true example: 0.7 top_p: title: Top P type: number description: >- Cumulative probability for token choices. An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. Is recommended altering this, top_k or temperature but not more than one of these. minimum: 0 maximum: 1 nullable: true example: 1 top_k: title: Top K type: integer description: >- Amount limit of token choices. An alternative to sampling with temperature, the model considers the results of the first K tokens with higher probability. So 10 means only the first 10 tokens with higher probability are considered. Is recommended altering this, top_p or temperature but not more than one of these. minimum: 1 maximum: 100 nullable: true example: 5 presence_penalty: title: Presence Penalty type: number description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. Not currently implemented; accepted for API compatibility maximum: 2 minimum: -2 default: 0 nullable: true frequency_penalty: title: Frequency Penalty type: number description: >- Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. Not currently implemented; accepted for API compatibility maximum: 2 minimum: -2 default: 0 do_sample: title: do_sample type: boolean description: >- If true, sampling is enabled during output generation. If false, deterministic decoding is used. nullable: true stop: title: Stop description: >- Sequences where the API will stop generating tokens. The returned text will not contain the stop sequence. oneOf: - type: string example: |+ nullable: true - type: array items: type: string example: '["\n"]' nullable: true stream: title: Stream type: boolean description: >- If set, partial message deltas will be sent. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. default: false nullable: true stream_options: title: StreamOptions type: object description: >- Options for streaming response. Only set this when setting stream as true additionalProperties: true properties: include_usage: anyOf: - type: boolean title: Include Usage description: Whether to include the usage metrics in a final chunk or not nullable: true nullable: true logprobs: title: Logprobs type: boolean description: >- This is not yet supported by our models in completions API. Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`. default: false nullable: true top_logprobs: title: Top Logprobs type: integer description: >- This is not yet supported by our models in completions API. An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used. maximum: 20 minimum: 0 nullable: true 'n': title: 'N' type: integer description: >- How many completions to generate for each prompt. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens`. maximum: 1 minimum: 1 default: 1 nullable: true example: 1 logit_bias: title: Logit Bias type: object description: >- Modify the likelihood of specified tokens appearing in the generation. Accepts a JSON object that maps tokens (specified by their token ID in the model tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. Values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. nullable: true seed: title: Seed description: >- If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. nullable: true type: integer required: - model - prompt examples: - prompt: >- <|begin_of_text|><|start_header_id|>system<|end_header_id|> You are a helpful assistant.<|eot_id|><|start_header_id|>user<|end_header_id|> create a poem using palindromes<|eot_id|><|start_header_id|>assistant<|end_header_id|> max_tokens: 2048 model: gpt-oss-120b stream: false temperature: 0.7 top_p: 1 CompletionResponse: title: Completion Response type: object description: ompletion response returned by the model properties: choices: title: Choices type: array items: $ref: '#/components/schemas/CompletionChoice' minItems: 1 created: title: Created type: number description: >- The Unix timestamp (in seconds) of when the chat completion was created. id: title: Id type: string description: A unique identifier for the chat completion. model: title: Model description: The model used for the chat completion. type: string object: title: Object type: string description: The object type, always `chat.completion`. enum: - chat.completion const: chat.completion system_fingerprint: title: System fingerprint type: string description: Backend configuration that the model runs with. usage: $ref: '#/components/schemas/Usage' required: - choices - created - id - model - object - system_fingerprint - usage examples: - choices: - finish_reason: stop index: 0 text: >- In madam moon's silver glow, Aha, a palindrome to know, Radar spins, a circular tale, Level heads prevail, without fail. A man, a plan, a canal, Panama! Able was I ere I saw Elba, A Santa at NASA, a curious sight, Do geese see God, in the pale moonlight? Mr. Owl ate my metal worm, Do nine men interpret? Nine men, I nod, Never odd or even, a palindrome's might, Madam, in Eden, I'm Adam. Aibohphobia, a fear to confess, A palindrome's symmetry, I must address, Refer, a word that reads the same, A palindrome's beauty, in its circular game. In the stillness of the night, Ava, a palindrome, shining bright, Hannah, a name that reads the same, A palindrome's magic, in its circular flame. Note: Please keep in mind that creating a poem using palindromes can be a challenging task, and the resulting poem may not be as cohesive or flowing as one that doesn't rely on palindromes. However, I hope you enjoy the attempt! created: 1737583288.6076705 id: 83a7809d-e18f-44f9-9ab7-2bc494c6c661 model: gpt-oss-120b object: chat.completion system_fingerprint: fastcoe usage: acceptance_rate: 4.058139324188232 completion_tokens: 350 completion_tokens_after_first_per_sec: 248.09314856382406 completion_tokens_after_first_per_sec_first_ten: 249.67922929952655 completion_tokens_per_sec: 238.91966176995348 end_time: 1737583289.7345645 is_last_response: true prompt_tokens: 43 start_time: 1737583288.264706 time_to_first_token: 0.06312894821166992 total_latency: 1.4649275719174653 total_tokens: 393 total_tokens_per_sec: 268.27264878740493 CompletionStreamResponse: title: Completion Stream Response type: object description: streamed chunk of a completion response returned by the model additionalProperties: true properties: choices: title: Choices type: array description: A list of chat completion choices. items: $ref: '#/components/schemas/CompletionChunkChoice' minItems: 0 nullable: true created: title: Created type: number description: >- The Unix timestamp (in seconds) of when the chat completion was created. id: title: Id type: string description: A unique identifier for the chat completion. model: title: Model description: The model used for the chat completion. type: string object: title: Object type: string description: The object type, always `chat.completion.chunk`. enum: - chat.completion.chunk const: chat.completion.chunk system_fingerprint: title: System fingerprint type: string description: Backend configuration that the model runs with. usage: $ref: '#/components/schemas/Usage' required: - choices - created - id - model - object - system_fingerprint examples: - choices: - delta: role: assistant content: '' index: 0 finish_reason: null logprobs: null created: 1737642515.6076705 id: 15fcaba4-1c4a-48fc-bc6e-05b55ddfb30b model: gpt-oss-120b object: chat.completion.chunk system_fingerprint: fastcoe - choices: - delta: role: assistant content: in index: 0 finish_reason: null logprobs: null created: 1737642515.6076705 id: 15fcaba4-1c4a-48fc-bc6e-05b55ddfb30b model: gpt-oss-120b object: chat.completion.chunk system_fingerprint: fastcoe - choices: - delta: content: '' index: 0 finish_reason: length logprobs: null created: 1737642515.6076705 id: 15fcaba4-1c4a-48fc-bc6e-05b55ddfb30b model: gpt-oss-120b object: chat.completion.chunk system_fingerprint: fastcoe - choices: [] created: 1737642515.6076705 id: 15fcaba4-1c4a-48fc-bc6e-05b55ddfb30b model: gpt-oss-120b object: chat.completion.chunk system_fingerprint: fastcoe usage: acceptance_rate: 3 completion_tokens: 100 completion_tokens_after_first_per_sec: 262.2771255106759 completion_tokens_after_first_per_sec_first_ten: 266.98193514986144 completion_tokens_after_first_per_sec_graph: 266.98193514986144 completion_tokens_per_sec: 217.87260449707574 end_time: 1737642515.9077535 is_last_response: true prompt_tokens: 43 prompt_tokens_details: cached_tokens: 0 start_time: 1737642515.4458635 time_to_first_token: 0.0844266414642334 total_latency: 0.4589838186899821 total_tokens: 143 total_tokens_per_sec: 311.55782443081836 GeneralError: title: GeneralError type: object description: other kind of errors properties: error: type: object properties: code: title: code type: string description: error code nullable: true message: title: message type: string description: error message param: title: param type: string description: error params nullable: true type: title: type type: string description: error type error_model_output: title: Error Model Output type: string description: >- Raw model output that could not be parsed. Present on `server_error` responses when the model produced output that failed internal parsing (e.g. a malformed tool call JSON). nullable: true request_id: title: request_id type: string description: unique request identifier for debugging nullable: true required: - error SimpleError: title: SimpleError type: object description: other kind of simple schema errors properties: error: title: error type: string description: error detail. nullable: true required: - error CompletionChoice: title: Completion Choice type: object additionalProperties: true properties: message: $ref: '#/components/schemas/CompletionResponseMessage' text: title: Text type: string description: model response finish_reason: title: Finish Reason type: string description: >- The reason the model stopped generating tokens. Will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `tool_calls` if the model called a tool. enum: - stop - length - tool_calls index: title: Index type: integer description: The index of the choice in the list of choices logprobs: title: Logprobs anyOf: - $ref: '#/components/schemas/LogProbs' description: >- currently not supported in completions API, always null will be returned nullable: true required: - finish_reason - index - text Usage: title: Usage type: object description: >- Usage metrics for the completion, embeddings,transcription or translation request additionalProperties: true properties: acceptance_rate: title: Acceptance Rate type: number description: acceptance rate completion_tokens: title: Completion Tokens type: integer description: number of tokens generated in completion completion_tokens_after_first_per_sec: title: Completion Tokens After First Per Sec type: number description: completion tokens per second after first token generation completion_tokens_after_first_per_sec_first_ten: title: Completion Tokens After First Per Sec First Ten type: number description: completion tokens per second after first token generation first ten completion_tokens_after_first_per_sec_graph: title: Completion Tokens After First Per Sec Graph type: number description: completion tokens per second after first token generation completion_tokens_per_sec: title: Completion Tokens Per Sec type: number description: completion tokens per second end_time: title: End Time type: number description: The Unix timestamp (in seconds) of when the generation finished. is_last_response: title: Is Last Response type: boolean description: >- whether or not is last response, always true for non streaming response const: true prompt_tokens_details: title: Prompt tokens details type: object description: Extra tokens details additionalProperties: true properties: cached_tokens: title: Cached tokens description: amount of cached tokens type: integer prompt_tokens: title: Prompt Tokens type: integer description: number of tokens used in the prompt sent start_time: title: Start Time type: number description: The Unix timestamp (in seconds) of when the generation started. time_to_first_token: title: Time To First Token type: number description: also TTF, time (in seconds) taken to generate the first token time_to_first_token_graph: title: Time To First Token Graph type: number description: >- Time (in seconds) to first token, adjusted for graph rendering. May differ slightly from time_to_first_token. stop_reason: title: Stop Reason type: string description: >- The reason generation stopped (e.g. "stop", "length"). Mirrors the choice-level finish_reason but reported at the usage level. nullable: true completion_tokens_details: title: Completion Tokens Details type: object description: Breakdown of completion token consumption. additionalProperties: true properties: reasoning_tokens: title: Reasoning Tokens type: integer description: >- Number of tokens consumed by the model's internal reasoning process. Only present on reasoning-capable models. nullable: true total_latency: title: Total Latency type: number description: total time (in seconds) taken to generate the full generation total_tokens: title: Total Tokens type: integer description: prompt tokens + completion tokens total_tokens_per_sec: title: Total Tokens Per Sec type: number description: tokens per second including prompt and completion nullable: true examples: - completion_tokens: 260 completion_tokens_after_first_per_sec: 422.79282728043336 completion_tokens_after_first_per_sec_first_ten: 423.6108998455803 completion_tokens_after_first_per_sec_graph: 423.6108998455803 completion_tokens_per_sec: 314.53312043711406 completion_tokens_details: reasoning_tokens: 55 end_time: 1776189309.02061 is_last_response: true prompt_tokens: 90 prompt_tokens_details: cached_tokens: 0 start_time: 1776189308.193988 stop_reason: stop time_to_first_token: 0.21402883529663086 time_to_first_token_graph: 0.2102978229522705 total_latency: 0.8266220092773438 total_tokens: 350 total_tokens_per_sec: 423.40996981919204 - prompt_tokens: 43 total_tokens: 393 CompletionChunkChoice: title: Completion Chunk Choice type: object additionalProperties: true properties: text: title: Text type: string description: model generation response finish_reason: title: Finish Reason type: string description: >- The reason the model stopped generating tokens. Will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `tool_calls` if the model called a tool. enum: - stop - length nullable: true index: title: Index type: integer description: The index of the choice in the list of choices logprobs: title: Logprobs anyOf: - $ref: '#/components/schemas/LogProbs' description: >- currently not supported in completions API, always null will be returned nullable: true required: - text CompletionResponseMessage: title: Completion Response Message type: object description: completion response message object additionalProperties: true properties: role: title: Role type: string description: The role of the messages author enum: - assistant - user - system - tool content: title: Content type: string description: The contents of the assistant message. nullable: true tool_calls: title: Tool Calls type: array items: $ref: '#/components/schemas/AssistantToolCall' description: The tool calls generated by the model. nullable: true required: - role - content LogProbs: title: Completion Log Probs type: object description: Completion Log Probs object additionalProperties: true properties: content: $ref: '#/components/schemas/LogProbsContent' required: - content examples: - content: - token: ' Hello' logprob: -0.00012340000000000002 bytes: - 32 - 72 - 101 - 108 - 108 - 111 top_logprobs: - token: ' Hello' logprob: -0.00012340000000000002 bytes: - 32 - 72 - 101 - 108 - 108 - 111 - token: ' Hi' logprob: -8.243 bytes: - 32 - 72 - 105 - token: '!' logprob: -0.0023456 bytes: - 33 top_logprobs: - token: '!' logprob: -0.0023456 bytes: - 33 - token: ',' logprob: -6.712 bytes: - 44 AssistantToolCall: title: AssistantToolCall type: object additionalProperties: true properties: function: $ref: '#/components/schemas/AssistantToolCallFunction' id: title: Id type: string description: ID of the tool call. nullable: true type: title: Type type: string description: type of the tool cal. only `function` is supported. enum: - function const: function nullable: true index: title: index description: index of tool call chunk only used when using streaming type: integer nullable: true required: - function LogProbsContent: title: Log Probs Content additionalProperties: true properties: bytes: title: Bytes anyOf: - items: type: integer type: array nullable: true logprob: title: Logprob type: number token: title: Token type: string top_logprobs: $ref: '#/components/schemas/TopLogProbs' required: - token - logprob - top_logprobs examples: - token: ' Hello' logprob: -0.00012340000000000002 bytes: - 32 - 72 - 101 - 108 - 108 - 111 top_logprobs: - token: ' Hello' logprob: -0.00012340000000000002 bytes: - 32 - 72 - 101 - 108 - 108 - 111 - token: ' Hi' logprob: -8.243 bytes: - 32 - 72 - 105 AssistantToolCallFunction: title: AssistantToolCallFunction type: object description: The tool that the model called. additionalProperties: true properties: name: title: Name type: string description: The name of the function to call. nullable: true arguments: title: Arguments type: string description: >- The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function. nullable: true TopLogProbs: title: TopLogProbs type: object additionalProperties: true properties: bytes: title: Bytes anyOf: - items: type: integer type: array - type: 'null' logprob: title: Logprob type: number token: title: Token type: string required: - token - logprob examples: - token: ' Hello' logprob: -0.00012340000000000002 bytes: - 32 - 72 - 101 - 108 - 108 - 111 - token: ' Hi' logprob: -8.243 bytes: - 32 - 72 - 105 securitySchemes: api_key: type: http description: >- SambaNova API key, sent as a bearer token in the `Authorization` header (`Authorization: Bearer `). Default authentication scheme used by the SambaNova SDK across every OpenAI compatible endpoint. scheme: bearer bearerFormat: apiKey ````