> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a chat completion
Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes, text, images, audio, video, files, function calling, reasoning, and structured outputs. Compatible with the OpenAI Chat Completions API format.
## Authentication
Bearer token. Use your API key as the bearer token in the Authorization header.
Format: `Bearer `
## Request
This endpoint expects an object.
List of messages for the conversation. Each message has a `role` and `content`.
Value: `system`.
The system message content. Can be a string or array of text content parts.
Optional name for the system message.
Value: `user`.
The user message content. Can be a string or array of content parts.
Value: `text`.
The text content.
Cache control for this content part.
Value: `ephemeral`.
Cache TTL. Supported values: `5m`, `1h`.
Value: `image_url`.
Image URL object.
URL of the image. Supports `data:` URLs for base64 encoded images.
Image detail level for vision models. Supported values: `auto`, `low`, `high`.
Value: `input_audio`.
Audio input data.
Base64 encoded audio data.
Audio format (e.g., `wav`, `mp3`, `flac`, `m4a`, `ogg`, `aiff`, `aac`). Supported formats vary by provider.
Value: `video_url`.
Video input object.
URL of the video. Supports `data:` URLs for base64 encoded video.
Value: `file`.
File content for document processing.
File content as base64 data URL or URL.
File ID for previously uploaded files.
Original filename.
Optional name for the user.
Value: `developer`.
The developer message content. Can be a string or array of text content parts.
Optional name for the developer message.
Value: `assistant`.
The assistant message content. Can be a string, array of content parts, or null (when tool\_calls are present).
Optional name for the assistant.
Tool calls made by the assistant.
Tool call identifier.
Value: `function`.
The function called.
Function name.
Function arguments as JSON string.
Refusal message if content was refused.
Reasoning output text.
Detailed reasoning information for extended thinking models.
Value: `reasoning.summary`.
The reasoning summary text.
Reasoning detail ID.
Format. Supported values: `unknown`, `openai-responses-v1`, `azure-openai-responses-v1`, `xai-responses-v1`, `anthropic-claude-v1`, `google-gemini-v1`.
Value: `reasoning.encrypted`.
Encrypted reasoning data.
Reasoning detail ID.
Format identifier.
Value: `reasoning.text`.
The reasoning text content.
Signature for verification.
Reasoning detail ID.
Format identifier.
Generated images from image generation models. Each item has `image_url.url`.
Audio output data.
Audio output identifier.
Base64 encoded audio data.
Audio transcript.
Audio expiration timestamp.
Value: `tool`.
Tool response content. Can be a string or array of content parts (text, image, audio, video, file).
ID of the assistant message tool call this message responds to.
The model to use for the completion. Browse available models at [sunra.ai/models](https://sunra.ai/models).
Optional provider routing preferences. Omit for automatic routing. See [Provider routing](/llm/provider-routing) for supported fields and provider discovery.
If set to `true`, partial message deltas will be sent as server-sent events (SSE). Streams are subject to an idle timeout and a lifetime ceiling — see [Output limits and stream lifetime](/llm/limits#stream-lifetime).
Maximum tokens in completion. Replaces `max_tokens` as the preferred parameter. On providers that do not honor this field the gateway translates it into `max_tokens`; when both are set, the smaller one applies. See [Output limits](/llm/limits).
Maximum tokens in completion. Deprecated — use `max_completion_tokens` instead. Note: some providers enforce a minimum of 16. A value above the model's own output ceiling is rejected with `400` rather than reduced.
Sampling temperature between 0 and 2. Higher values like 0.8 make output more random, lower values like 0.2 make it more focused and deterministic.
Nucleus sampling parameter (0-1). An alternative to temperature sampling where the model considers the tokens with top\_p probability mass.
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.
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.
Up to 4 sequences where the API will stop generating further tokens.
How many chat completion choices to generate for each input message.
Whether to return log probabilities of the output tokens.
An integer between 0 and 20 specifying the number of most likely tokens to return at each token position. `logprobs` must be set to `true` if this parameter is used.
Token logit bias adjustments. Modify the likelihood of specified tokens appearing in the completion. Maps token IDs to bias values from -100 to 100.
Configuration options for reasoning models.
Constrains effort on reasoning. Supported values: `xhigh`, `high`, `medium`, `low`, `minimal`, `none`.
Controls reasoning summary verbosity. Supported values: `auto`, `concise`, `detailed`.
An object specifying the format that the model must output.
Value: `text`.
Value: `json_object`.
Value: `json_schema`.
JSON Schema configuration.
Schema name (a-z, A-Z, 0-9, underscores, dashes, max 64 chars).
Schema description for the model.
JSON Schema object.
Enable strict schema adherence.
Value: `grammar`.
Custom grammar for text generation.
If specified, the system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result.
A list of tools the model may call.
The type of the tool. Value: `function`.
The function definition.
Function name (a-z, A-Z, 0-9, underscores, dashes, max 64 chars).
A description of what the function does.
The parameters the function accepts, described as a JSON Schema object.
Whether to enable strict schema adherence.
Cache control for this tool definition.
Value: `ephemeral`.
Cache TTL. Supported values: `5m`, `1h`.
Controls which (if any) tool is called by the model. `none` means no tool calls. `auto` means the model decides. `required` means the model must call a tool. Can also specify a particular function.
Value: `function`.
The name of the function to call.
Whether to enable parallel function calling during tool use.
Output modalities for the response. Supported values: `text`, `image`, `audio`.
Key-value pairs for additional object information. Maximum 16 pairs, 64 character keys, 512 character values.
Enable automatic prompt caching. When set, the system automatically applies cache breakpoints to the last cacheable block in the request. Currently supported for Anthropic Claude models.
Value: `ephemeral`.
Cache TTL. Supported values: `5m`, `1h`.
A unique identifier representing your end-user, which can help monitor and detect abuse.
## Response
Successful chat completion response.
A unique identifier for the chat completion.
The object type. Always `chat.completion`.
The Unix timestamp (in seconds) of when the chat completion was created.
The model used for the chat completion.
A list of chat completion choices. Can be more than one if `n` is greater than 1.
The index of the choice in the list of choices.
The reason the model stopped generating tokens. Possible values: `stop`, `length`, `tool_calls`, `content_filter`, `error`.
A chat completion message generated by the model.
Always `assistant`.
The text contents of the message. Null when tool\_calls are present.
The tool calls generated by the model.
The ID of the tool call.
Value: `function`.
The function that the model called.
The name of the function to call.
The arguments in JSON string format.
Refusal message if the content was refused.
Reasoning output text.
Detailed reasoning information for extended thinking models.
Value: `reasoning.summary`.
The reasoning summary text.
Detail ID.
Format identifier.
Value: `reasoning.encrypted`.
Encrypted reasoning data.
Detail ID.
Format identifier.
Value: `reasoning.text`.
The reasoning text.
Verification signature.
Detail ID.
Format identifier.
Generated images. Each item contains `image_url.url`.
Audio output data.
Audio output identifier.
Base64 encoded audio data.
Audio transcript.
Audio expiration timestamp.
Log probability information for the choice.
Log probabilities for content tokens. Each item contains `token`, `logprob`, `bytes`, and `top_logprobs`.
Log probabilities for refusal tokens.
Usage statistics for the completion request.
Number of tokens in the prompt.
Number of tokens in the generated completion.
Total number of tokens used in the request (prompt + completion).
Detailed prompt token usage.
Number of cached prompt tokens.
Tokens written to cache. Only returned for models with explicit caching.
Audio input tokens.
Video input tokens.
Detailed completion token usage.
Tokens used for reasoning.
Tokens used for audio output.
Accepted prediction tokens.
Rejected prediction tokens.
This fingerprint represents the backend configuration that the model runs with. Can be used with the `seed` parameter to understand when backend changes have been made.
```bash cURL theme={null}
curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemini-2.5-flash",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "What is the capital of France?"
}
]
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api-llm.sunra.ai/v1/chat/completions",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json"
},
json={
"model": "google/gemini-2.5-flash",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"}
]
}
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api-llm.sunra.ai/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": "Bearer ",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "google/gemini-2.5-flash",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "What is the capital of France?" }
]
})
});
const data = await response.json();
console.log(data);
```
```json 200 theme={null}
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1677652288,
"model": "google/gemini-2.5-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The capital of France is Paris.",
"refusal": null
},
"finish_reason": "stop",
"logprobs": null
}
],
"system_fingerprint": "fp_44709d6fcb",
"usage": {
"prompt_tokens": 25,
"completion_tokens": 8,
"total_tokens": 33,
"prompt_tokens_details": null,
"completion_tokens_details": null
}
}
```