> ## Documentation Index > Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create chat completion > Calls an enabled model with its protocol-specific reviewed capabilities. Query GET /v1/models for tools, JSON formats, sampling, reasoning and combination restrictions. Capability review covers every callable route. New combinations are documentation-based, pending individual live validation. Reserves and settles validated usage; disable automatic SDK retries. Responses is stateless/store:false; hosted tools and stored IDs are unsupported. All callable routes use parameter passthrough (parameter_policy upstream-first). Capability lists are guidance, not local rejection lists; ordinary schemas and extension fields are forwarded. Native responses/reasoning output is retained. Model provider 400/422 rejections release holds; provider failures, timeouts and interrupted streams need reconciliation. ## OpenAPI ````yaml /openapi.json post /v1/chat/completions openapi: 3.1.0 info: title: OmniRelay API version: 1.0.0 description: >- OpenAI-compatible gateway for reviewed real text models. Access is workspace-specific; query your own model list for capabilities and customer prices. servers: - url: https://api.omnirelay.ai security: - bearerAuth: [] tags: - name: Service - name: Models - name: Chat - name: Management - name: Responses - name: Embeddings - name: Images - name: Videos paths: /v1/chat/completions: post: tags: - Chat summary: Create chat completion description: >- Calls an enabled model with its protocol-specific reviewed capabilities. Query GET /v1/models for tools, JSON formats, sampling, reasoning and combination restrictions. Capability review covers every callable route. New combinations are documentation-based, pending individual live validation. Reserves and settles validated usage; disable automatic SDK retries. Responses is stateless/store:false; hosted tools and stored IDs are unsupported. All callable routes use parameter passthrough (parameter_policy upstream-first). Capability lists are guidance, not local rejection lists; ordinary schemas and extension fields are forwarded. Native responses/reasoning output is retained. Model provider 400/422 rejections release holds; provider failures, timeouts and interrupted streams need reconciliation. operationId: createChatCompletion parameters: - name: X-Gateway-Tags in: header required: false description: >- Tags for this call as comma-separated `key=value` pairs, for example `client=acme,env=prod`. Merged with the API key's default tags; the `tags` body field wins on the same key. `X-OmniRelay-Tags` is the same header under its former name and stays accepted. schema: type: string example: client=acme,env=prod - name: X-Gateway-Metadata in: header required: false description: >- Send `enabled` to receive a `gateway_metadata` block describing what the gateway decided. Any other value, or no header, leaves the response unchanged. `X-OmniRelay-Metadata` is the same header under its former name and stays accepted. schema: type: string enum: - enabled requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' examples: liveProvider: summary: Enabled live workspace only value: model: gpt-6-luna messages: - role: system content: Answer concisely. - role: user content: Hello OmniRelay max_completion_tokens: 64 reasoning_effort: none liveStream: summary: Enabled live workspace only value: model: deepseek-v4-pro messages: - role: user content: Hello OmniRelay max_tokens: 128 stream: true stream_options: include_usage: true responses: '200': description: >- Completion with settled usage and cost, or an SSE stream. A failed stream may emit an error after HTTP 200 and ends without [DONE]. headers: X-Request-ID: description: >- OmniRelay request ID for diagnostics. It is separate from the provider trace, header and response IDs. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ChatCompletion' examples: live: summary: Enabled live workspace only value: id: chatcmpl-example object: chat.completion created: 1790985600 model: gpt-6-luna choices: - index: 0 message: role: assistant content: Hello. finish_reason: stop usage: prompt_tokens: 10 completion_tokens: 5 total_tokens: 15 cost_microusd: 30 text/event-stream: schema: type: string example: >+ data: {"id":"chatcmpl-fixture","object":"chat.completion.chunk","model":"gpt-6-luna","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":"stop"}]} data: [DONE] '400': description: >- Invalid JSON, tags or parameters; unsupported model capabilities; or context_length_exceeded. Rejected before dispatch. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unsupported_parameter request_id: 2f6c1d0e9a '401': $ref: '#/components/responses/Unauthorized' '402': description: >- inference_budget_or_access_denied: wallet, key or platform budget cannot cover the reservation; member_budget_exceeded: member cap exceeded. Rejected before dispatch. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_balance request_id: 2f6c1d0e9a '403': description: >- `model_not_allowed`: the API key is limited to other models. Nothing is charged. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: model_not_allowed request_id: 2f6c1d0e9a '404': description: >- `model_unavailable`: the model does not exist or is disabled in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: model_unavailable request_id: 2f6c1d0e9a '413': description: >- payload_too_large: the request body exceeds 4 MiB (4194304 bytes of UTF-8). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: payload_too_large request_id: 2f6c1d0e9a '429': description: 'rate_limited: the effective account request limit was exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited request_id: 2f6c1d0e9a '502': description: >- Model provider rejection, transport failure, invalid response or missing/invalid usage. A dispatched call may retain a hold pending reconciliation; this status does not prove the provider did not bill. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- channel_unavailable, live_provider_not_configured, live_provider_unavailable, runtime_maintenance, or storage_unavailable. Credential and maintenance checks reject before dispatch. An ambiguous dispatched request remains pending; do not automatically retry a paid call. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: live_provider_not_configured request_id: 2f6c1d0e9a components: schemas: ChatCompletionRequest: type: object required: - model - messages properties: model: type: string description: An active model ID from `GET /v1/models`. example: gpt-6-luna messages: type: array minItems: 1 maxItems: 2000 description: >- 1 to 2000 text messages within the model context contract. Request body limit: 4 MiB (4194304 bytes of UTF-8). Provider-context-ceiling reserves input/output separately; the provider validates actual context fit. items: $ref: '#/components/schemas/Message' stream: type: boolean description: Deliver the answer as server-sent events instead of one JSON body. default: false stream_options: type: object description: Only read when `stream` is true. properties: include_usage: type: boolean description: >- On successful SSE, request a final empty-choices chunk with usage and settled cost_microusd. Final usage is always collected. default: false tags: type: object description: >- Tags for this call. At most 10 after merging with the header and the key's default tags. Keys are 1 to 64 characters and stored in lowercase; values are 1 to 128 characters. Both use only letters, digits and `- _ . : /`. Keys starting with `gateway:` or `omnirelay:` are reserved. A `tags` field that is not an object is ignored. additionalProperties: type: string example: client: acme project: invoices max_tokens: type: integer minimum: 1 description: >- Live only. Positive integer; send one output-limit field, never both. The gateway normalizes it for the model. Read limits.output_tokens and limits.default_output_tokens from your model list; GPT 5.4 Mini uses 64/256; most other integrated text routes default to 32,000 up to 128,000 (Gemini 3.1 Pro Preview and Gemini 3.6 Flash: 65,536); DeepSeek V4 Pro, GLM 5.3 and Kimi K3 use 4,096/4,096. max_completion_tokens: type: integer minimum: 1 description: >- Live only. Positive integer; send one output-limit field, never both. The gateway normalizes it for the model. Read limits.output_tokens and limits.default_output_tokens from your model list; GPT 5.4 Mini uses 64/256; most other integrated text routes default to 32,000 up to 128,000 (Gemini 3.1 Pro Preview and Gemini 3.6 Flash: 65,536); DeepSeek V4 Pro, GLM 5.3 and Kimi K3 use 4,096/4,096. temperature: type: number minimum: 0 maximum: 2 description: >- Forwarded; the model provider decides and may ignore unsupported values. Consult model-specific documented guidance. top_p: type: number minimum: 0 maximum: 1 description: >- Forwarded; the model provider decides and may ignore unsupported values. Consult model-specific documented guidance. frequency_penalty: type: number minimum: -2 maximum: 2 description: Live only and only when supported by the reviewed endpoint. presence_penalty: type: number minimum: -2 maximum: 2 description: Live only and only when supported by the reviewed endpoint. seed: type: integer description: Live only and only when supported by the reviewed endpoint. stop: oneOf: - type: string maxLength: 256 - type: array minItems: 1 maxItems: 4 items: type: string maxLength: 256 description: Live only and only when supported by the reviewed endpoint. 'n': type: integer enum: - 1 description: Live only. Multiple completions per request are not supported. tools: type: array minItems: 1 maxItems: 64 items: type: object required: - type - function properties: type: type: string enum: - function function: type: object required: - name properties: name: type: string maxLength: 64 description: type: string maxLength: 4096 parameters: type: object strict: type: boolean description: >- Live only when tools are supported. Function tools only; strict tools and JSON Schema keywords require separate support. See the provider integration guide. tool_choice: oneOf: - type: string enum: - auto - none - required - type: object required: - type - function properties: type: type: string enum: - function function: type: object required: - name properties: name: type: string description: >- Use auto, none or required when tool_choice is advertised. Named function selection additionally requires capabilities.named_tool_choice. parallel_tool_calls: type: boolean description: Live only and only when supported by the reviewed endpoint. response_format: type: object required: - type properties: type: type: string enum: - text - json_object - json_schema json_schema: type: object required: - name - schema properties: name: type: string maxLength: 64 description: type: string maxLength: 4096 schema: type: object strict: type: boolean description: >- Forwarded; the model provider decides and may ignore unsupported values. Consult model-specific documented guidance. reasoning_effort: type: string description: >- Forwarded; the model provider decides and may ignore unsupported values. Consult model-specific documented guidance. thinking: type: object additionalProperties: false required: - type properties: type: type: string enum: - enabled - disabled description: >- Only for models advertising thinking_modes; GLM 5.3 only accepts enabled. tool_stream: type: boolean description: For models advertising tool_stream; true requires stream:true. additionalProperties: true description: >- Parameter passthrough: ordinary extension fields are forwarded; authentication, text/function protocol and budget settlement boundaries remain enforced. ChatCompletion: type: object required: - id - object - created - model - choices - usage - cost_microusd properties: id: type: string example: chatcmpl-2f6c1d0e9a object: type: string enum: - chat.completion created: type: integer description: Unix timestamp in seconds. model: type: string choices: type: array items: type: object properties: index: type: integer message: $ref: '#/components/schemas/AssistantMessage' finish_reason: type: string enum: - stop - length - tool_calls - content_filter usage: type: object description: >- Validated provider usage; missing or invalid usage prevents automatic settlement. Prompt usage includes cache partitions; completion includes reasoning. Omitted detail counters do not erase token usage. properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer prompt_tokens_details: type: object properties: cached_tokens: type: integer minimum: 0 cache_write_tokens: type: integer minimum: 0 completion_tokens_details: type: object properties: reasoning_tokens: type: integer minimum: 0 required: - prompt_tokens - completion_tokens - total_tokens cost_microusd: type: integer description: >- Settled customer charge in micro-USD, using frozen prices, token partitions, tiers and discount. Round the full sum, apply the discount and round up again. This is the final charge, not the maximum hold. omnirelay_metadata: $ref: '#/components/schemas/RequestMetadata' gateway_metadata: $ref: '#/components/schemas/RequestMetadata' Error: type: object required: - error properties: error: type: object required: - code - message - type properties: code: type: string example: model_unavailable message: type: string example: The model does not exist or is disabled. description: >- Short English description for logs and SDK exceptions. Its wording can change; branch on code. type: type: string example: not_found_error description: >- Error family by HTTP status: invalid_request_error, authentication_error, insufficient_quota, permission_error, not_found_error, conflict_error, rate_limit_error, service_unavailable or api_error. param: type: string maxLength: 200 description: >- Rejected request field path when identifiable; never a parameter value. Responses uses native field names. request_id: type: string description: Present on chat completion, Responses and embeddings errors. Message: type: object required: - role properties: role: type: string enum: - system - developer - user - assistant - tool content: oneOf: - type: string maxLength: 1048576 - type: array maxItems: 64 items: type: object required: - type - text properties: type: type: string enum: - text text: type: string maxLength: 1048576 - type: 'null' description: >- Text values or text parts: at most 1048576 characters per text value, within the 4 MiB request body limit and the model context window. Roles require model capability support. name: type: string maxLength: 64 tool_call_id: type: string tool_calls: type: array maxItems: 64 items: $ref: '#/components/schemas/ToolCall' reasoning_content: type: - string - 'null' maxLength: 1048576 description: >- Assistant reasoning history only when reasoning_history is advertised, including DeepSeek tool turns. AssistantMessage: type: object required: - role properties: role: type: string enum: - system - developer - user - assistant - tool content: oneOf: - type: string maxLength: 1048576 - type: array maxItems: 64 items: type: object required: - type - text properties: type: type: string enum: - text text: type: string maxLength: 1048576 - type: 'null' description: >- Text values or text parts: at most 1048576 characters per text value, within the 4 MiB request body limit and the model context window. Roles require model capability support. name: type: string maxLength: 64 tool_call_id: type: string tool_calls: type: array maxItems: 64 items: $ref: '#/components/schemas/ToolCall' reasoning_content: type: string description: >- Optional reasoning text returned only when the model capability reasoning_content is true. In SSE it appears in choices[].delta.reasoning_content. It is not a request field. RequestMetadata: type: object description: >- Present only when the request sent `X-Gateway-Metadata: enabled`. Returned under both `gateway_metadata` and its former name `omnirelay_metadata`, with the same content. On a stream it rides the first chunk. properties: request_id: type: string description: The request ID, as in `X-Request-ID`. requested: type: string description: The model ID you sent. model: type: string description: The model that served the call. provider: type: string description: The provider of that model. mode: type: string enum: - live description: 'live: a real provider was called.' strategy: type: string enum: - direct description: >- How the model was resolved. Every model has one channel today, so this is always `direct`. attempt: type: integer description: >- 1-based position of the attempt that served. Always 1 until fallback exists. attempts: type: array description: Every attempt made, in order. items: type: object properties: provider: type: string model: type: string mode: type: string tags: type: object additionalProperties: type: string description: The tags recorded for this call, or `{}`. deprecated_header: type: string description: >- Present when the request sent an old-style header (`X-OmniRelay-Tags` or `X-OmniRelay-Metadata`) together with its new name carrying a different value: names the old header that was ignored. ToolCall: type: object required: - id - type - function properties: id: type: string maxLength: 128 type: type: string enum: - function function: type: object required: - name - arguments properties: name: type: string maxLength: 64 arguments: type: string maxLength: 65536 responses: Unauthorized: description: '`unauthorized`: the API key is missing, revoked, or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key created in the OmniRelay console. The owner can view it again in the console after confirming their identity. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.