SambaNova Systems Chat completions API
The Chat completions API from SambaNova Systems — 1 operation(s) for chat completions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Sambanova Agents Service Audio Chat completions API
description: Service for Sambanova agents
version: 0.0.1
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://chat.sambanova.ai/api
security:
- api_key: []
tags:
- name: Chat completions
paths:
/chat/completions:
post:
operationId: createChatCompletion
tags:
- Chat completions
summary: Create chat-based completion
security:
- api_key: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
description: Chat prompt and parameters
required: true
responses:
'200':
description: 'Successful Response, Returns a ChatCompletionResponse object (non-streaming), or a stream of server-sent ChatCompletionStreamResponse object events ending with a response.completed event (when stream: true).'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ChatCompletionResponse'
- $ref: '#/components/schemas/ChatCompletionStreamResponse'
'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:
empty_messages:
summary: Empty messages array
value:
error:
message: 'Invalid ''messages'': empty array. Expected an array with minimum length 1, but got an empty array instead.'
type: invalid_request_error
param: messages
code: empty_array
request_id: d79vdot7os633dverihg
invalid_role:
summary: Invalid message role value
value:
error:
message: 'Invalid value: ''developerrr''. Supported values are: ''system'', ''assistant'', ''user'', ''function'', ''tool'', and ''developer''.'
type: invalid_request_error
param: messages[0].role
code: invalid_value
request_id: d79vdit7os6aemenqav0
null_content:
summary: Null user message content
value:
error:
message: 'Invalid value for ''content'': expected a string, got null.'
type: invalid_request_error
param: messages.[5].content
code: null
request_id: d79vcsd7os6aemenqa80
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: Unhandled error
'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
x-codeSamples:
- lang: JavaScript
source: "import SambaNova from 'sambanova';\n\nconst client = new SambaNova({\n apiKey: process.env['SAMBANOVA_API_KEY'], // This is the default and can be omitted\n});\n\nconst completion = await client.chat.completions.create({\n messages: [{ content: 'create a poem using palindromes', role: 'user' }],\n model: 'gpt-oss-120b',\n});\n\nconsole.log(completion);"
- lang: Python
source: "import os\nfrom sambanova import SambaNova\n\nclient = SambaNova(\n api_key=os.environ.get(\"SAMBANOVA_API_KEY\"), # This is the default and can be omitted\n)\nfor completion in client.chat.completions.create(\n messages=[{\n \"content\": \"create a poem using palindromes\",\n \"role\": \"user\",\n }],\n model=\"gpt-oss-120b\",\n):\n print(completion)"
components:
schemas:
SystemMessage:
title: System Message
type: object
additionalProperties: true
properties:
role:
title: Role
type: string
description: The role of the messages author, in this case `system`.
enum:
- system
const: system
content:
title: Content
anyOf:
- type: string
- title: Text Content Part Array
type: array
items:
$ref: '#/components/schemas/TextContent'
description: The contents of the system message.
nullable: true
required:
- role
- content
CompletionResponseDelta:
title: Completion Response Delta
type: object
description: completion response delta chunk generated by streamed model responses.
additionalProperties: true
properties:
role:
title: Role
type: string
description: The role of the messages author
enum:
- assistant
- user
- system
- tool
nullable: true
content:
title: Content
type: string
description: The contents of the assistant message.
nullable: true
reasoning:
title: Reasoning
type: string
description: Reasoning (returned by reasoning models like gpt oss)
nullable: true
channel:
title: Channel
type: string
description: Channel (returned by reasoning models like gpt oss)
nullable: true
tool_calls:
title: Tool Calls
type: array
items:
$ref: '#/components/schemas/AssistantToolCall'
description: The tool calls generated by the model.
nullable: true
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
ResponseFormatJSONSchema:
title: ResponseFormatJSONSchema
type: object
additionalProperties: true
description: Specifies that the model should produce output conforming to a given JSON schema.
properties:
json_schema:
$ref: '#/components/schemas/JSONSchema'
type:
const: json_schema
enum:
- json_schema
title: Type
type: string
required:
- json_schema
- type
example:
type: json_schema
json_schema:
name: User
description: JSON schema for a simple user object
strict: false
schema:
type: object
properties:
id:
type: string
description: Unique identifier for the user
name:
type: string
description: Full name of the user
required:
- id
- name
ImageContent:
title: Image Content
type: object
additionalProperties: true
properties:
type:
title: Type
type: string
description: type of content to send. in this case `image_url`.
enum:
- image_url
const: image_url
image_url:
title: Image Url
type: object
properties:
url:
title: Url
type: string
description: Either a URL of the image or the base64 encoded image data. currently only base64 encoded image supported
required:
- type
- image_url
JSONSchema:
title: JSONSchema
type: object
additionalProperties: true
description: A JSON Schema definition the model's structured output. Follows standard JSON Schema syntax.
properties:
description:
type: string
title: Description
description: description the json schema
nullable: true
name:
title: Name
type: string
description: name of the object schema
schema:
type: object
title: Schema
description: Actual json schema object
nullable: true
strict:
type: boolean
title: Strict
description: whether or not to do an strict validation of the schema
nullable: true
default: false
required:
- name
VideoContent:
title: Video Content
type: object
additionalProperties: true
properties:
type:
title: Type
type: string
description: type of content to send. in this case `video_url`.
enum:
- video_url
const: video_url
video_url:
title: Video Url
type: object
properties:
url:
title: Url
type: string
description: Either a URL of the video or the base64 encoded video data.
required:
- type
- video_url
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
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
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
ChatCompletionStreamResponse:
title: Chat Completion Stream Response
type: object
description: streamed chunk of a chat 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/ChatCompletionChunkChoice'
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
- choices:
- delta:
content: ' Hello'
index: 0
finish_reason: null
logprobs:
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
created: 1737642516.1076705
id: 15fcaba4-1c4a-48fc-bc6e-05b55ddfb30c
model: gpt-oss-120b
object: chat.completion.chunk
system_fingerprint: fastcoe
ResponseFormatJSONObject:
title: ResponseFormatJSONObject
type: object
description: Specifies that the model should produce output as a raw JSON object.
additionalProperties: true
properties:
type:
const: json_object
enum:
- json_object
title: Type
type: string
required:
- type
example:
type: json_object
FunctionParameters:
title: Function Parameters
type: object
additionalProperties: true
description: The parameters the functions accepts, described as a JSON Schema object. see the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.
ToolMessage:
title: Tool Message
type: object
additionalProperties: true
properties:
role:
title: Role
type: string
description: The role of the messages author, in this case `tool`.
enum:
- tool
const: tool
content:
title: Content
description: The contents of the tool message.
anyOf:
- type: string
- title: Text Content Part Array
type: array
items:
$ref: '#/components/schemas/TextContent'
required:
- content
- role
AssistantMessage:
title: Assistant Message
type: object
additionalProperties: true
properties:
role:
title: Role
type: string
description: The role of the messages author, in this case `assistant`.
enum:
- assistant
const: assistant
content:
title: Content
anyOf:
- type: string
- title: Text Content Part Array
type: array
items:
$ref: '#/components/schemas/TextContent'
description: The contents of the assistant message.
nullable: true
reasoning:
title: Reasoning
type: string
description: Reasoning (returned by reasoning models like gpt oss)
nullable: true
channel:
title: Channel
type: string
description: Channel (returned by reasoning models like gpt oss)
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
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
EnableThinking:
title: Enable Thinking
type: boolean
description: Enables the model's internal reasoning or "thinking" mode, if supported by the chat template (deepseek models).
example: true
ResponseFormatText:
title: ResponseFormatText
type: object
description: Specifies that the model should produce output as plain text. This value is not supported yet in the chat compeltions api, if this behavior is desired do not set response format.
additionalProperties: true
properties:
type:
const: text
enum:
- text
title: Type
type: string
required:
- type
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
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
ChatCompletionResponse:
title: Chat Completion Response
type: object
description: chat completion response returned by the model
properties:
choices:
title: Choices
type: array
items:
$ref: '#/components/schemas/ChatCompletionChoice'
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
message:
content: '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 resultin
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sambanova-systems/refs/heads/main/openapi/sambanova-systems-chat-completions-api-openapi.yml