API reference
Chat completions reference
Build multimodal chat-completion requests, stream events, and execute function tools safely.
Build a request
POST /v1/chat/completions follows the OpenAI chat-completions shape and adds top-level media_ids for content uploaded through the Ox Media API.
| Field | Type | Notes |
|---|---|---|
model | string | Required. Use an ID returned by GET /v1/models. |
messages | array | Required and non-empty. Roles are developer, system, user, assistant, or tool. |
media_ids | string[] | Optional Ox extension for previously uploaded images or videos. |
temperature, top_p | number | Optional sampling controls. Prefer changing one at a time. |
max_tokens, max_completion_tokens | number | Optional output bounds supported for client compatibility. |
stop | string or string[] | Optional stop sequence or sequences. |
tools, tool_choice | object[] / string or object | Optional OpenAI-compatible function tools. |
response_format | object | Optional structured-response configuration supported by the selected model. |
seed, user | number / string | Optional compatibility fields. |
stream | boolean | Set to true for server-sent events. |
stream_options.include_usage | boolean | Requests a final streaming usage block when supported. |
Messages can contain plain text or multimodal content parts. Remote image and video URLs must be reachable by the inference service; use the Media API for private or repeatedly queried content.
{
"model": "MODEL_ID",
"messages": [{
"role": "user",
"content": [
{ "type": "video_url", "video_url": { "url": "https://example.com/clip.mp4" } },
{ "type": "text", "text": "What happens after the door opens?" }
]
}],
"temperature": 0
}
Stream server-sent events
Set stream: true and read each data: event until [DONE]. Use curl --no-buffer during development so chunks appear as they arrive.
curl --fail-with-body --no-buffer "$OX_API_BASE_URL/v1/chat/completions" \
--header "Authorization: Bearer $OX_API_KEY" \
--header "Content-Type: application/json" \
--data '{"model":"MODEL_ID","messages":[{"role":"user","content":"Summarize the scene."}],"stream":true,"stream_options":{"include_usage":true}}'
Each JSON event uses object: "chat.completion.chunk"; append choices[0].delta.content and stop on [DONE]. Cancel the upstream request when the downstream user disconnects.
Use tools safely
Function definitions use the OpenAI-compatible tools and tool_choice fields. Treat generated arguments as untrusted input: parse JSON, validate it against the function schema, authorize the signed-in user again, apply timeouts, and return bounded results. Never let a model choose credentials, tenant IDs, or authorization policy.