--- title: "Create chat completions" method: POST path: "/v1/chat/completions" tags: ["Chat"] --- # Create chat completions `POST /v1/chat/completions` ## Request - Base URL: `https://api.atoma.network` - URL: `https://api.atoma.network/v1/chat/completions` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) This function processes chat completion requests by determining whether to use streaming or non-streaming response handling based on the request payload. For streaming requests, it configures additional options to track token usage. ## Returns Returns a Response containing either: - A streaming SSE connection for real-time completions - A single JSON response for non-streaming completions ## Errors Returns an error status code if: - The request processing fails - The streaming/non-streaming handlers encounter errors - The underlying inference service returns an error ## Request body - CreateChatCompletionRequest: Represents the create chat completion request. This is used to represent the create chat completion request in the chat completion request. It can be either a chat completion or a chat completion stream. - `frequency_penalty` number, float, nullable: Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far - `function_call` unknown - `functions` unknown[], nullable: A list of functions the model may generate JSON inputs for - unknown - `logit_bias` object, nullable: Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the 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. The exact effect will vary per model, but 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. - `max_completion_tokens` integer, nullable: The maximum number of tokens to generate in the chat completion - `max_tokens` integer, nullable: The maximum number of tokens to generate in the chat completion - `messages` ChatCompletionMessage[], required: A list of messages comprising the conversation so far - union: A message that is part of a conversation which is based on the role of the author of the message. This is used to represent the message in the chat completion request. It can be either a system message, a user message, an assistant message, or a tool message. - object: The role of the messages author, in this case system. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `name` string, nullable: An optional name for the participant. Provides the model information to differentiate between participants of the same role. - `role` 'system', required - object: The role of the messages author, in this case user. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `name` string, nullable: An optional name for the participant. Provides the model information to differentiate between participants of the same role. - `role` 'user', required - object: The role of the messages author, in this case assistant. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `name` string, nullable: An optional name for the participant. Provides the model information to differentiate between participants of the same role. - `refusal` string, nullable: The refusal message by the assistant. - `role` 'assistant', required - `tool_calls` ToolCall[]: The tool calls generated by the model, such as function calls. - `function` ToolCallFunction, required: Represents the function that the model called. This is used to represent the function that the model called in the chat completion request. It can be either a function or a tool call. - `arguments` string, required: 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. - `name` string, required: The name of the function to call. - `id` string, required: The ID of the tool call. - `type` string, required: The type of the tool. Currently, only function is supported. - object: The role of the messages author, in this case tool. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `role` 'tool', required - `tool_call_id` string: Tool call that this message is responding to. - `model` string, required: ID of the model to use - `n` integer, nullable: How many chat completion choices to generate for each input message - `parallel_tool_calls` boolean, nullable: Whether to enable parallel tool calls. - `presence_penalty` number, float, nullable: Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far - `response_format` ResponseFormat: The format to return the response in. This is used to represent the format to return the response in in the chat completion request. It can be either text, json_object, or json_schema. - `json_schema` JsonSchemaResponseFormat: The format to return the response in. This is used to represent the format to return the response in in the chat completion request. It can be either text, json_object, or json_schema. - `description` string, nullable: The description of the response format. - `name` string, required: The name of the response format. - `schema` unknown - `strict` boolean, nullable: Whether to strictly validate the JSON schema. - `type` 'text' | 'json_object' | 'json_schema', required: The format to return the response in. - `seed` integer, nullable: If specified, our system will make a best effort to sample deterministically - `service_tier` string, nullable: Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarantee. If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarantee. When not set, the default behavior is 'auto'. - `stop` string[], nullable: Up to 4 sequences where the API will stop generating further tokens - `stream` boolean, nullable: Whether to stream back partial progress. Must be false for this request type. - `stream_options` StreamOptions: Specifies the stream options for the request. - `include_usage` boolean, nullable: If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value. - `temperature` number, float, nullable: What sampling temperature to use, between 0 and 2 - `tool_choice` union: A tool choice that can be used in a chat completion. This is used to represent the tool choice in the chat completion request. It can be either a literal tool choice or a named tool choice. - 'none' | 'auto': A literal tool choice that can be used in a chat completion. This is used to represent the literal tool choice in the chat completion request. It can be either none or auto. - ChatCompletionNamedToolChoiceParam: A named tool choice that can be used in a chat completion. This is used to represent the named tool choice in the chat completion request. - `function` ChatCompletionNamedFunction, required: A named function that can be used in a chat completion. This is used to represent the named function in the chat completion request. - `name` string, required: The name of the function. - `type` string, required: The type of the tool choice. - `tools` ChatCompletionToolsParam[], nullable: A list of tools the model may call - `function` ChatCompletionToolFunctionParam, required: A function that can be used in a chat completion. - `description` string, nullable: The description of the function. - `name` string, required: The name of the function. - `parameters` object, nullable: The parameters of the function. - `strict` boolean, nullable: Whether to strictly validate the parameters of the function. - `type` string, required: The type of the tool. - `top_logprobs` integer, nullable: 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. - `top_p` number, float, nullable: An alternative to sampling with temperature - `user` string, nullable: A unique identifier representing your end-user ## Response `200` Chat completions - ChatCompletionResponse: Represents the chat completion response. This is used to represent the chat completion response in the chat completion request. It can be either a chat completion or a chat completion stream. - `choices` ChatCompletionChoice[], required: A list of chat completion choices. - `finish_reason` string, nullable: The reason the chat completion was finished. - `index` integer, required: The index of this choice in the list of choices. - `logprobs` ChatCompletionLogProbs: Represents the chat completion log probs. This is used to represent the chat completion log probs in the chat completion request. It can be either a chat completion log probs or a chat completion log probs choice. - `content` ChatCompletionLogProbsContent[], nullable: The log probs of the chat completion. - `top_logprobs` ChatCompletionLogProb[], required - `bytes` integer[], nullable: A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token. - `logprob` number, float, required: The log prob of the chat completion. - `token` string, required: The token of the chat completion. - `message` union, required: A message that is part of a conversation which is based on the role of the author of the message. This is used to represent the message in the chat completion request. It can be either a system message, a user message, an assistant message, or a tool message. - object: The role of the messages author, in this case system. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `name` string, nullable: An optional name for the participant. Provides the model information to differentiate between participants of the same role. - `role` 'system', required - object: The role of the messages author, in this case user. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `name` string, nullable: An optional name for the participant. Provides the model information to differentiate between participants of the same role. - `role` 'user', required - object: The role of the messages author, in this case assistant. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `name` string, nullable: An optional name for the participant. Provides the model information to differentiate between participants of the same role. - `refusal` string, nullable: The refusal message by the assistant. - `role` 'assistant', required - `tool_calls` ToolCall[]: The tool calls generated by the model, such as function calls. - `function` ToolCallFunction, required: Represents the function that the model called. This is used to represent the function that the model called in the chat completion request. It can be either a function or a tool call. - `arguments` string, required: 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. - `name` string, required: The name of the function to call. - `id` string, required: The ID of the tool call. - `type` string, required: The type of the tool. Currently, only function is supported. - object: The role of the messages author, in this case tool. - `content` union: Represents the content of a message. This is used to represent the content of a message in the chat completion request. It can be either a text or an array of content parts. - string: The text contents of the message. - MessageContentPart[]: An array of content parts with a defined type, each can be of type text or image_url when passing in images. You can pass multiple images by adding multiple image_url content parts. Image input is only supported when using the gpt-4o model. - union: Represents a part of a message content. This is used to represent the content of a message in the chat completion request. It can be either a text or an image. - … - `role` 'tool', required - `tool_call_id` string: Tool call that this message is responding to. - `created` integer, required: The Unix timestamp (in seconds) of when the chat completion was created. - `id` string, required: A unique identifier for the chat completion. - `model` string, required: The model used for the chat completion. - `object` string, required: The object of the chat completion. - `service_tier` string, nullable: The service tier of the chat completion. - `system_fingerprint` string, nullable: The system fingerprint for the completion, if applicable. - `usage` CompletionUsage: Represents the completion usage. This is used to represent the completion usage in the chat completion request. It can be either a completion usage or a completion chunk usage. - `completion_tokens` integer, required: Number of tokens in the completion. - `prompt_tokens` integer, required: Number of tokens in the prompt. - `prompt_tokens_details` PromptTokensDetails - `audio_tokens` integer, required: The number of audio tokens - `cached_tokens` integer, required: The number of cached tokens - `total_tokens` integer, required: Total number of tokens used (prompt + completion). ## Other responses - `400`: Bad request - `401`: Unauthorized - `500`: Internal server error ## Changes - **2025-05-12** `f0bf5a2dde0f`: 1 info - added the required property `usage/oneOf[#/components/schemas/CompletionUsage]/prompt_tokens_details/oneOf[#/components/schemas/PromptTokensDetails]/audio_tokens` to the response with the `200` status - **2025-02-13** `972a6a82c154`: 2 breaking, 2 info - removed `subschema #1, subschema #2, subschema #3, subschema #4` from the `allOf[#/components/schemas/ChatCompletionRequest]/messages/items/` request property `oneOf` list - added `subschema #1: System, subschema #2: User, subschema #3: Assistant, subschema #4: Tool` to the `choices/items/message` response property `oneOf` list for the response status `200` - added `subschema #1: System, subschema #2: User, subschema #3: Assistant, subschema #4: Tool` to the `allOf[#/components/schemas/ChatCompletionRequest]/messages/items/` request property `oneOf` list - removed `subschema #1, subschema #2, subschema #3, subschema #4` from the `choices/items/message` response property `oneOf` list for the response status `200` - …earlier changes not shown [Operation history](https://skmtc.dev/atomaai/apis/atoma-proxy/changes/v1/chat/completions/post.md) --- [API](https://skmtc.dev/atomaai/apis/atoma-proxy.md) - [All operations](https://skmtc.dev/atomaai/apis/atoma-proxy/llms.txt) - [OpenAPI document](https://skmtc.dev/atomaai/apis/atoma-proxy/revisions/07694b7228b0?raw)