> For the complete documentation index, see [llms.txt](https://nsclouds.gitbook.io/aillm.nscloud.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nsclouds.gitbook.io/aillm.nscloud.ai/conversation-apis/volcengine/chat.md).

# Chat Completions

### 1. Overview

Volcengine exposes conversation capabilities in this environment.

{% hint style="success" %}
This endpoint provides an OpenAI-compatible Chat Completions path. Actual parameter support may vary by vendor and model.
{% endhint %}

**Supported models：**

* `doubao-seed-2-0-lite-260215`
* `doubao-seed-2-0-pro-260215`

### 2. API Details

## Create chat completion

> Provides an OpenAI-compatible Chat Completions endpoint. Supported parameters and behavior may vary by model.

```json
{"openapi":"3.1.0","info":{"title":"NSCloud AI API Documentation","version":"1.11.0"},"tags":[{"name":"chat_completions_volcengine","description":"Volcengine's chat completions API"}],"servers":[{"url":"https://aillm.nscloud.ai","description":"Global Server"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"http","scheme":"bearer","description":"Authenticate using Bearer token format: 'Bearer YOUR_SECRET_TOKEN'"}},"schemas":{"CreateChatCompletionRequest":{"type":"object","description":"Chat Completions request body.","properties":{"model":{"type":"string","description":"Model ID to invoke."},"messages":{"type":"array","description":"Ordered conversation history sent to the model.","items":{"$ref":"#/components/schemas/ChatMessage"}},"temperature":{"type":"number","description":"Sampling temperature. Higher values make output more random.","default":1},"top_p":{"type":"number","description":"Nucleus sampling parameter."},"presence_penalty":{"type":"number","description":"Penalize tokens based on whether they have appeared."},"frequency_penalty":{"type":"number","description":"Penalize tokens based on how frequently they have appeared."},"stop":{"description":"Up to four stop sequences.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"max_completion_tokens":{"type":"integer","description":"Maximum number of output tokens the model may generate."},"n":{"type":"integer","description":"Number of candidate completions to generate.","default":1},"seed":{"type":"integer","description":"Best-effort deterministic sampling seed."},"reasoning_effort":{"type":"string","description":"Reasoning effort level for supported reasoning models."},"response_format":{"$ref":"#/components/schemas/ChatResponseFormat"},"modalities":{"type":"array","description":"Requested output modalities, such as text or audio.","items":{"type":"string"}},"audio":{"$ref":"#/components/schemas/ChatAudioRequestConfig"},"store":{"type":"boolean","description":"Whether to store the response for later retrieval or distillation."},"metadata":{"type":"object","description":"Developer-defined metadata associated with the request.","additionalProperties":true},"service_tier":{"type":"string","description":"Requested service tier when supported."},"user":{"type":"string","description":"End-user identifier."},"tools":{"type":"array","description":"Tool declarations available to the model.","items":{"$ref":"#/components/schemas/ChatToolDefinition"}},"tool_choice":{"$ref":"#/components/schemas/ChatToolChoice"},"parallel_tool_calls":{"type":"boolean","description":"Whether the model may emit multiple tool calls in parallel."},"stream":{"type":"boolean","description":"Whether to return the response as a stream.","default":false},"stream_options":{"$ref":"#/components/schemas/ChatStreamOptions"}},"required":["model","messages"]},"ChatMessage":{"description":"Chat message object.","oneOf":[{"$ref":"#/components/schemas/ChatDeveloperMessage"},{"$ref":"#/components/schemas/ChatSystemMessage"},{"$ref":"#/components/schemas/ChatUserMessage"},{"$ref":"#/components/schemas/ChatAssistantMessage"},{"$ref":"#/components/schemas/ChatToolMessage"},{"$ref":"#/components/schemas/ChatFunctionMessage"}]},"ChatDeveloperMessage":{"type":"object","description":"Developer message. Supports text-only content.","properties":{"role":{"type":"string","enum":["developer"]},"name":{"type":"string","description":"Optional participant name."},"content":{"$ref":"#/components/schemas/ChatTextOnlyContent"}},"required":["role","content"],"additionalProperties":true},"ChatTextOnlyContent":{"description":"Text-only chat message content.","oneOf":[{"type":"string","description":"Plain text content."},{"type":"array","description":"Array of text content parts.","items":{"$ref":"#/components/schemas/ChatMessageTextPart"}}]},"ChatMessageTextPart":{"type":"object","description":"Text content part.","properties":{"type":{"type":"string","description":"Part type.","enum":["text"]},"text":{"type":"string","description":"Text content."}},"required":["type","text"]},"ChatSystemMessage":{"type":"object","description":"System message. Supports text-only content.","properties":{"role":{"type":"string","enum":["system"]},"name":{"type":"string","description":"Optional participant name."},"content":{"$ref":"#/components/schemas/ChatTextOnlyContent"}},"required":["role","content"],"additionalProperties":true},"ChatUserMessage":{"type":"object","description":"User message. Supports text, image, audio, and file input parts.","properties":{"role":{"type":"string","enum":["user"]},"name":{"type":"string","description":"Optional participant name."},"content":{"description":"User message content.","oneOf":[{"type":"string","description":"Plain text content."},{"type":"array","description":"Array of structured multimodal content parts.","items":{"oneOf":[{"$ref":"#/components/schemas/ChatMessageTextPart"},{"$ref":"#/components/schemas/ChatMessageImagePart"},{"$ref":"#/components/schemas/ChatMessageInputAudioPart"},{"$ref":"#/components/schemas/ChatMessageFilePart"}]}}]}},"required":["role","content"],"additionalProperties":true},"ChatMessageImagePart":{"type":"object","description":"Image input content part. Add multiple image_url parts to send multiple images.","properties":{"type":{"type":"string","description":"Part type.","enum":["image_url"]},"image_url":{"$ref":"#/components/schemas/ChatMessageImageUrl"}},"required":["type","image_url"]},"ChatMessageImageUrl":{"type":"object","description":"Image URL payload.","properties":{"url":{"type":"string","description":"Publicly accessible image URL or image data URL. Common image formats are supported; PNG may be used in examples."},"detail":{"type":"string","description":"Optional image understanding detail level.","enum":["auto","low","high"]}},"required":["url"]},"ChatMessageInputAudioPart":{"type":"object","description":"Audio input content part.","properties":{"type":{"type":"string","description":"Part type.","enum":["input_audio"]},"input_audio":{"$ref":"#/components/schemas/ChatMessageInputAudio"}},"required":["type","input_audio"]},"ChatMessageInputAudio":{"type":"object","description":"Audio input payload.","properties":{"data":{"type":"string","description":"Base64-encoded audio data."},"format":{"type":"string","description":"Audio format.","enum":["wav","mp3"]}},"required":["data","format"]},"ChatMessageFilePart":{"type":"object","description":"File input content part for Chat Completions. Supports file_data and keeps file_id compatibility; external file URLs are not supported here. Use Responses input_file.file_url instead.","properties":{"type":{"type":"string","description":"Part type.","enum":["file"]},"file":{"$ref":"#/components/schemas/ChatMessageFileObject"}},"required":["type","file"]},"ChatMessageFileObject":{"type":"object","description":"File payload passed in a Chat Completions content part. Chat file parts support inline file_data and keep OpenAI-compatible file_id; file_data is recommended today. They do not support file_url. Use Responses input_file.file_url for external file URLs.","properties":{"file_id":{"type":"string","description":"OpenAI-compatible field. Previously uploaded file ID from the Files API; this platform capability is under construction/adaptation, and actual availability depends on file hosting and model-side support."},"file_data":{"type":"string","description":"Inline base64-encoded file content, recommended today."},"filename":{"type":"string","description":"File name used together with inline file content."}},"anyOf":[{"required":["file_id"]},{"required":["file_data"]}],"additionalProperties":false},"ChatAssistantMessage":{"type":"object","description":"Assistant message, including optional tool calls.","properties":{"role":{"type":"string","enum":["assistant"]},"name":{"type":"string","description":"Optional participant name."},"content":{"description":"Assistant message content.","oneOf":[{"$ref":"#/components/schemas/ChatTextOnlyContent"},{"type":"null","description":"Null content, typically used when assistant emits tool calls."}]},"tool_calls":{"type":"array","description":"Tool calls emitted by the assistant.","items":{"$ref":"#/components/schemas/ChatCompletionToolCall"}},"function_call":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionFunctionCall"},{"type":"null"}],"description":"Deprecated single function call payload."},"refusal":{"type":["string","null"],"description":"Refusal text when the model declines the request."},"audio":{"oneOf":[{"$ref":"#/components/schemas/ChatAudioResponseMetadata"},{"type":"null"}],"description":"Audio payload metadata associated with the message."}},"required":["role"],"additionalProperties":true},"ChatCompletionToolCall":{"description":"Tool call emitted by the assistant.","oneOf":[{"$ref":"#/components/schemas/ChatCompletionFunctionToolCall"},{"$ref":"#/components/schemas/ChatCompletionCustomToolCall"}]},"ChatCompletionFunctionToolCall":{"type":"object","description":"Function tool call emitted by the assistant.","properties":{"id":{"type":"string","description":"Tool call identifier."},"type":{"type":"string","description":"Tool call type.","enum":["function"]},"function":{"$ref":"#/components/schemas/ChatCompletionFunctionCall"}},"required":["id","type","function"],"additionalProperties":true},"ChatCompletionFunctionCall":{"type":"object","description":"Deprecated function call structure returned by some models.","properties":{"name":{"type":"string","description":"Function name."},"arguments":{"type":"string","description":"JSON string containing function arguments."}},"additionalProperties":true},"ChatCompletionCustomToolCall":{"type":"object","description":"Custom tool call emitted by the assistant.","properties":{"id":{"type":"string","description":"Tool call identifier."},"type":{"type":"string","description":"Tool call type.","enum":["custom"]},"custom":{"type":"object","description":"Custom tool call payload.","additionalProperties":true}},"required":["id","type","custom"],"additionalProperties":true},"ChatAudioResponseMetadata":{"type":"object","description":"Audio metadata returned with a chat message.","properties":{"id":{"type":"string","description":"Audio object identifier."},"expires_at":{"type":"integer","description":"Expiration timestamp when provided."},"transcript":{"type":"string","description":"Transcript associated with the audio output."}},"additionalProperties":true},"ChatToolMessage":{"type":"object","description":"Tool result message. Supports text-only content and requires the related tool call ID.","properties":{"role":{"type":"string","enum":["tool"]},"content":{"$ref":"#/components/schemas/ChatTextOnlyContent"},"tool_call_id":{"type":"string","description":"Tool call identifier this message responds to."}},"required":["role","content","tool_call_id"],"additionalProperties":true},"ChatFunctionMessage":{"type":"object","description":"Deprecated function result message. Use tool messages for new integrations.","properties":{"role":{"type":"string","enum":["function"]},"name":{"type":"string","description":"Function name."},"content":{"type":["string","null"],"description":"Function result content."}},"required":["role","name","content"],"additionalProperties":true},"ChatResponseFormat":{"type":"object","description":"Structured output format configuration.","properties":{"type":{"type":"string","description":"Response format type such as text, json_object, or json_schema."},"json_schema":{"type":"object","description":"JSON Schema configuration when type=json_schema.","additionalProperties":true}},"additionalProperties":true},"ChatAudioRequestConfig":{"type":"object","description":"Audio output request configuration.","properties":{"voice":{"type":"string","description":"Voice name for audio output."},"format":{"type":"string","description":"Audio format."}},"additionalProperties":true},"ChatToolDefinition":{"description":"Tool declaration for Chat Completions.","oneOf":[{"$ref":"#/components/schemas/ChatFunctionToolDefinition"},{"$ref":"#/components/schemas/ChatCustomToolDefinition"}]},"ChatFunctionToolDefinition":{"type":"object","description":"Function tool declaration for Chat Completions.","properties":{"type":{"type":"string","description":"Tool type.","enum":["function"]},"function":{"$ref":"#/components/schemas/ChatToolFunction"}},"required":["type","function"],"additionalProperties":true},"ChatToolFunction":{"type":"object","description":"Function definition used by tool declarations.","properties":{"name":{"type":"string","description":"Function name."},"description":{"type":"string","description":"Human-readable function description."},"parameters":{"type":"object","description":"JSON Schema describing function arguments.","additionalProperties":true},"strict":{"type":"boolean","description":"Whether to enforce strict schema adherence."}},"required":["name"],"additionalProperties":true},"ChatCustomToolDefinition":{"type":"object","description":"Custom tool declaration for Chat Completions.","properties":{"type":{"type":"string","description":"Tool type.","enum":["custom"]},"custom":{"$ref":"#/components/schemas/ChatCustomTool"}},"required":["type","custom"],"additionalProperties":true},"ChatCustomTool":{"type":"object","description":"Custom tool definition used by tool declarations.","properties":{"name":{"type":"string","description":"Custom tool name."},"description":{"type":"string","description":"Human-readable custom tool description."},"format":{"type":"object","description":"Optional custom tool input format definition.","additionalProperties":true}},"required":["name"],"additionalProperties":true},"ChatToolChoice":{"description":"Tool choice strategy.","anyOf":[{"type":"string","description":"Simple strategy such as none, auto, or required.","enum":["none","auto","required"]},{"$ref":"#/components/schemas/ChatNamedFunctionToolChoice"},{"$ref":"#/components/schemas/ChatNamedCustomToolChoice"},{"$ref":"#/components/schemas/ChatAllowedToolsChoice"},{"type":"object","description":"Provider-specific tool choice object.","additionalProperties":true}]},"ChatNamedFunctionToolChoice":{"type":"object","description":"Explicitly choose a named function tool.","properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","properties":{"name":{"type":"string","description":"Function tool name."}},"required":["name"],"additionalProperties":true}},"required":["type","function"],"additionalProperties":true},"ChatNamedCustomToolChoice":{"type":"object","description":"Explicitly choose a named custom tool.","properties":{"type":{"type":"string","enum":["custom"]},"custom":{"type":"object","properties":{"name":{"type":"string","description":"Custom tool name."}},"required":["name"],"additionalProperties":true}},"required":["type","custom"],"additionalProperties":true},"ChatAllowedToolsChoice":{"type":"object","description":"Restrict tool choice to an allowed subset of tools.","properties":{"type":{"type":"string","enum":["allowed_tools"]},"allowed_tools":{"type":"object","description":"Allowed tool choice configuration.","properties":{"mode":{"type":"string","description":"Tool selection mode for the allowed subset."},"tools":{"type":"array","description":"Allowed tool declarations.","items":{"$ref":"#/components/schemas/ChatToolDefinition"}}},"required":["mode","tools"],"additionalProperties":true}},"required":["type","allowed_tools"],"additionalProperties":true},"ChatStreamOptions":{"type":"object","description":"Streaming options for Chat Completions.","properties":{"include_usage":{"type":"boolean","description":"Include a final usage chunk in streamed responses."},"include_obfuscation":{"type":"boolean","description":"Include obfuscation metadata when supported."}},"additionalProperties":true},"ChatCompletionResponse":{"type":"object","description":"Chat Completions success response.","properties":{"id":{"type":"string","description":"Unique response ID."},"object":{"type":"string","description":"Object type, usually chat.completion."},"created":{"type":"integer","description":"Unix timestamp in seconds when the response was created."},"model":{"type":"string","description":"Model ID actually used for the request."},"service_tier":{"type":"string","description":"Service tier used for the request when provided."},"system_fingerprint":{"type":"string","description":"Backend configuration fingerprint when available."},"request_id":{"type":"string","description":"Request identifier when exposed by the provider."},"choices":{"type":"array","description":"Candidate outputs returned by the model.","items":{"$ref":"#/components/schemas/ChatCompletionChoice"}},"usage":{"$ref":"#/components/schemas/Usage"}}},"ChatCompletionChoice":{"type":"object","description":"A single chat completion candidate.","properties":{"index":{"type":"integer","description":"Zero-based position of this choice in the returned list."},"message":{"$ref":"#/components/schemas/ChatCompletionResponseMessage"},"finish_reason":{"description":"Reason generation stopped, such as stop, length, or tool_calls.","type":["string","null"]},"logprobs":{"type":["object","null"],"description":"Optional token-level log probability details.","additionalProperties":true}}},"ChatCompletionResponseMessage":{"type":"object","description":"A generated message in a chat completion.","properties":{"role":{"type":"string","description":"Role of the generated message, usually assistant."},"content":{"description":"Generated message text. May be null in some tool-calling flows.","type":["string","null"]},"refusal":{"type":["string","null"],"description":"Refusal text when the assistant declines to answer."},"annotations":{"type":"array","description":"Optional annotations such as citations or URL references.","items":{"$ref":"#/components/schemas/ChatCompletionAnnotation"}},"tool_calls":{"type":"array","description":"Tool calls emitted by the assistant.","items":{"$ref":"#/components/schemas/ChatCompletionToolCall"}},"function_call":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionFunctionCall"},{"type":"null"}],"description":"Deprecated single function call payload."},"audio":{"oneOf":[{"$ref":"#/components/schemas/ChatAudioResponseMetadata"},{"type":"null"}],"description":"Audio payload returned with the message."}}},"ChatCompletionAnnotation":{"type":"object","description":"Annotation attached to a response message.","additionalProperties":true},"Usage":{"type":"object","description":"Token usage summary.","properties":{"prompt_tokens":{"type":"integer","description":"Number of input tokens consumed."},"completion_tokens":{"type":"integer","description":"Number of output tokens consumed."},"total_tokens":{"type":"integer","description":"Total number of tokens consumed."},"input_tokens":{"type":"integer","description":"Number of input tokens consumed for protocols that expose this field."},"output_tokens":{"type":"integer","description":"Number of output tokens consumed for protocols that expose this field."},"completion_tokens_details":{"type":"object","description":"Optional breakdown of completion token usage.","properties":{"reasoning_tokens":{"type":"integer","description":"Tokens consumed by reasoning or chain-of-thought style generation."}},"additionalProperties":true},"input_tokens_details":{"type":"object","description":"Optional breakdown of input token usage.","properties":{"text_tokens":{"type":"integer","description":"Input tokens attributed to text."},"image_tokens":{"type":"integer","description":"Input tokens attributed to images."}},"additionalProperties":true}}},"ErrorResponse":{"type":"object","description":"Error response payload.","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","description":"Error detail object.","properties":{"message":{"type":"string","description":"Human-readable error message."},"type":{"type":"string","description":"Error type."},"param":{"description":"Parameter associated with the error, if any.","type":["string","null"]},"code":{"description":"Machine-readable error code, if any.","type":["string","null"]}}}},"responses":{"ErrorResponse":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/chat/completions":{"post":{"tags":["chat_completions_volcengine"],"summary":"Create chat completion","description":"Provides an OpenAI-compatible Chat Completions endpoint. Supported parameters and behavior may vary by model.","operationId":"createChatCompletion_volcengine","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChatCompletionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Streaming response is returned in Server-Sent Events format, each event is a line of JSON data block starting with 'data: ', ending with 'data: [DONE]'."}}}},"400":{"$ref":"#/components/responses/ErrorResponse"},"401":{"$ref":"#/components/responses/ErrorResponse"},"429":{"$ref":"#/components/responses/ErrorResponse"}}}}}}
```