Parameters — Markdown source
Raw Markdown for copying or feeding to AI agents.
> **AI Agents**: Index `/api/llms.txt` | Full EN `/api/llms-full-en.txt` | Full ZH `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`
# Parameters
Request parameters for `POST /v1/chat/completions`.
## Required
| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | string | Model id from `GET /v1/models` |
| `messages` | array | OpenAI chat messages; `content` may be a string or a content-part array (text + images / video, etc.) |
## Common optional parameters
SupaNexus **passes through** standard OpenAI parameters when the model supports them. Check `supported_parameters` on the model object.
| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| `stream` | boolean | **Stream tokens** as they are generated; use `true` for chat UIs, `false` for batch jobs | `"stream": true` |
| `temperature` | number | **Randomness**: higher = more creative; lower = more stable and repeatable. Try `0.7` for chat, `0`–`0.3` for factual Q&A | `"temperature": 0.7` |
| `top_p` | number | Another randomness control (nucleus sampling); usually tune **either** this **or** `temperature`, not both aggressively | `"top_p": 0.9` |
| `max_tokens` | integer | **Cap reply length** in tokens — avoids overly long answers or runaway cost | `"max_tokens": 1024` |
| `frequency_penalty` | number | **Discourage repeating the same words** — higher values reduce “looping” phrasing | `"frequency_penalty": 0.5` |
| `presence_penalty` | number | **Encourage new topics** — higher values reduce staying stuck on one point | `"presence_penalty": 0.3` |
| `stop` | string or array | Generation **stops** when the model outputs these strings — useful for sections or lists | `"stop": ["\n\n", "END"]` |
| `tools` | array | Declare **functions the model may call** (weather, orders, etc.); requires Function Calling support | See example below |
| `tool_choice` | string or object | Tool policy: `"auto"` (model decides), `"none"` (disable), `"required"` (must call a tool) | `"tool_choice": "auto"` |
| `response_format` | object | Force a **structured output** shape, e.g. valid JSON only | `"response_format": {"type": "json_object"}` |
| `user` | string | **End-user id** in your app — helps abuse tracking; on OpenAI models can also improve Prompt Cache hit rate | `"user": "user-42"` |
`tools` example (simplified):
```json
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "City name, e.g. Shanghai" }
},
"required": ["city"]
}
}
}
]
```
## Multimodal input
When the model supports vision or video, `messages[].content` may be a **content-part array** (OpenAI-compatible format).
Confirm via `GET /v1/models` that `architecture.input_modalities` includes `"image"` for images and/or `"video"` for video. Text-only models (`["text"]` only) reject media.
### Images (`image_url`)
#### Image URL example
```json
{
"model": "google/gemini-2.5-flash",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg"
}
}
]
}
]
}
```
#### Base64 image example
Set `image_url.url` to a data URI:
```json
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
}
```
Base64 inflates the body by about **33%**. The default body limit is **64 MB**; exceeding it returns **413** with `error.code` `request_too_large`. Prefer a publicly reachable URL for large images.
### Video (`video_url`)
When `input_modalities` includes `"video"` (e.g. `minimax/minimax-m3`, `moonshot/kimi-k2.6`), use a `video_url` content part.
**Whale v1 policy**:
| Allowed | Not allowed |
|---------|-------------|
| Public `http://` / `https://` video URLs (upstream fetches the media) | `data:` (base64), `file://`, `blob:`, vendor file refs (e.g. `mm_file://`, `ms://`) |
Invalid `video_url` values are rejected with **400** and are not forwarded. Do not send video as a data URI through the gateway — that would consume platform bandwidth.
#### Public video URL example
```json
{
"model": "minimax/minimax-m3",
"messages": [
{
"role": "user",
"content": [
{"type": "text", "text": "Summarize this video"},
{
"type": "video_url",
"video_url": {
"url": "https://example.com/demo.mp4",
"detail": "default"
}
}
]
}
]
}
```
Some upstreams also accept fields such as `fps` for frame sampling; they are passed through when supported.
### Limitation: Anthropic upstream models
When an OpenAI client (`POST /v1/chat/completions`) calls **`anthropic/*`**, the gateway translates the request and flattens messages to plain text — **images are dropped silently**. For images use [`POST /v1/messages`](./messages.md).
**Rule of thumb**: for images, align client protocol with upstream — `/v1/messages` for `anthropic/*`, `/v1/chat/completions` otherwise.
## Request handling
### Recognized fields
- `model` — model id for this call
- `stream` — SSE streaming vs JSON response
### Streaming usage
When `stream: true`, the response may include a `usage` object at the end (model-dependent).
### Other parameters
Remaining JSON fields are handled in an OpenAI-compatible way within body size limits.
## Body size limit
Default maximum request body: **64 MB** (`GATEWAY_OPENAPI_MAX_REQUEST_BODY_BYTES`).
Exceeding the limit returns **413** with `error.code` `request_too_large`. Large images may use data URIs; **large videos must use a public URL** — do not base64-encode video into the request body.
## Model-specific defaults
Each model may expose `default_parameters` in `GET /v1/models`. These are suggested defaults; the client may override them in the request.
## Related
- [Models](./models.md)
- [Chat Completions](./chat-completions.md)
- [Messages (Anthropic)](./messages.md)
- [Errors](./errors.md)