POST /v1/chat/completions
Create a chat completion
Creates a completion for the message list. Set stream: true for the SSE chunk stream (terminal usage chunk, then data: [DONE]). The model field takes an IronStratum alias from GET /v1/models.
Request
Request body fields for createChatCompletion | Field | Type | Required | Description |
| model | string | yes | IronStratum alias (from GET /v1/models). |
| messages | array of object | yes | OpenAI message shapes, including image parts (vision aliases) and tool_calls / tool results. |
| stream | boolean | no | — |
| max_completion_tokens | integer | no | Canonical max-token name. |
| max_tokens | integer | no | Legacy max-token name — honored identically. |
| temperature | number | no | — |
| top_p | number | no | — |
| top_k | integer | no | — |
| min_p | number | no | — |
| frequency_penalty | number | no | — |
| presence_penalty | number | no | — |
| stop | any | no | Stop sequence(s). |
| seed | integer | no | — |
| n | integer | no | — |
| logit_bias | object | no | — |
| user | string | no | — |
| parallel_tool_calls | boolean | no | — |
| tools | array of object | no | — |
| tool_choice | any | no | Tool selection mode or a named tool. |
| response_format | object | no | — |
| reasoning_effort | string enum | no | — |
| stream_options | object | no | The recognized inner surface is include_usage (boolean). |
| metadata | object | no | — |
| logprobs | boolean | no | — |
| top_logprobs | integer | no | — |
| session_id | string | no | Optional conversation UUID (delta-only session mode). When set, messages carry ONLY the new turn; the gateway assembles the stored prefix. An unseen id auto-creates the conversation. Canonical hyphenated hex, case-insensitive. Responses echo the field on session-mode turns only (additive, contract §10.1).
|
| store | any | no | NOT SUPPORTED — a clear 400 (invalid_param), never a silent ignore. |
| service_tier | any | no | NOT SUPPORTED — a clear 400 (invalid_param), never a silent ignore. |
Responses
200 The completion. Non-stream requests return application/json; stream: true returns text/event-stream of chat completion chunks ending with the final usage chunk and [DONE].
200 response fields for createChatCompletion | Field | Type | Required | Description |
| id | string | yes | — |
| object | string | yes | — |
| created | integer | yes | — |
| model | string | yes | — |
| choices | array of object | yes | — |
| usage | object | yes | — |
| session_id | string | no | Present only on session-mode turns: the echoed session_id from the request (additive, contract §10.1 — omitted on full-context turns).
|
400 400
400 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
401 401
401 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
402 402
402 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
403 403
403 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
404 404
404 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
409 409
409 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
429 429
429 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
500 500
500 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
502 502
502 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
503 503
503 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
504 504
504 response fields for createChatCompletion | Field | Type | Required | Description |
| error | object | yes | — |
Example
curl -X POST https://api.ironstratum.com/v1/chat/completions \
-H "Authorization: Bearer $IRONSTRATUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<model>","messages":[{"role":"<role>"}]}'
All operations ·
interactive reference ·
openapi.yaml