> ## Documentation Index > Fetch the complete documentation index at: https://docs.aixy-gateway.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a chat completion > Create an OpenAI-compatible chat completion. Use a provider-qualified model such as `openai/gpt-4.1-mini` to select a provider explicitly, or an `aixy/` reference to use a project routing policy. Set `stream` to `true` to receive incremental server-sent events. Aixy preserves matching native protocols and translates supported stateless conversations otherwise. Advanced fields without a supported translation are rejected explicitly. Aixy selects a compatible provider API for reviewed model contracts while preserving the requested reasoning effort. Plaintext assistant history in `reasoning` or `reasoning_content` is accepted during translation but is omitted when the destination has no compatible plaintext history carrier; it does not recreate signed or encrypted provider continuation. ## OpenAPI ````yaml /openapi.json post /v1/chat/completions openapi: 3.1.0 info: title: Aixy Inference API version: 0.1.0 description: >- Route requests to configured AI providers through OpenAI- and Anthropic-compatible APIs. Aixy applies project access, model policies, guardrails, routing, budgets, and usage attribution before forwarding inference traffic. Create connections, API keys and policies in the Aixy dashboard. The management API is a dashboard service and is not a public integration contract. Native provider features depend on the selected model and connection; translated requests support the documented conversation and function-tool subset. Unsupported combinations return explicit errors. Examples use illustrative model IDs; select an ID available to your project. servers: - url: https://api.aixy-gateway.com description: Aixy production gateway security: [] tags: - name: OpenAI description: OpenAI-compatible conversations, function tools and incremental streams. - name: Anthropic description: Anthropic-compatible messages and provider-native input token counting. - name: Decisions description: Typed, non-streaming classification and scoring inference. - name: Models description: Discover the models available to your project API key. paths: /v1/chat/completions: post: tags: - OpenAI summary: Create a chat completion description: >- Create an OpenAI-compatible chat completion. Use a provider-qualified model such as `openai/gpt-4.1-mini` to select a provider explicitly, or an `aixy/` reference to use a project routing policy. Set `stream` to `true` to receive incremental server-sent events. Aixy preserves matching native protocols and translates supported stateless conversations otherwise. Advanced fields without a supported translation are rejected explicitly. Aixy selects a compatible provider API for reviewed model contracts while preserving the requested reasoning effort. Plaintext assistant history in `reasoning` or `reasoning_content` is accepted during translation but is omitted when the destination has no compatible plaintext history carrier; it does not recreate signed or encrypted provider continuation. operationId: create_chat_completion parameters: - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/XAixyClient' - $ref: '#/components/parameters/XAixySession' - $ref: '#/components/parameters/XAixySessionId' - $ref: '#/components/parameters/XProvider' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' examples: basic: summary: Basic request value: model: openai/gpt-4.1-mini messages: - role: user content: Explain this code. max_completion_tokens: 256 stream: false functionTools: summary: Function tools (executed by your application) value: model: openai/gpt-4.1-mini messages: - role: user content: What is the weather in Paris? max_completion_tokens: 256 stream: false tools: - type: function function: name: get_weather description: Read the weather for a city. parameters: type: object properties: city: type: string required: - city additionalProperties: false streaming: summary: Incremental stream value: model: openai/gpt-4.1-mini messages: - role: user content: Explain this code. max_completion_tokens: 256 stream: true stream_options: include_usage: true toolHistory: summary: Continue after a function tool value: model: openai/gpt-4.1-mini messages: - role: user content: What is the weather in Paris? - role: assistant content: null tool_calls: - id: call_weather type: function function: name: get_weather arguments: '{"city":"Paris"}' - role: tool tool_call_id: call_weather content: '{"temperature_celsius":18}' max_completion_tokens: 256 stream: false responses: '200': description: Successful response or server-sent event stream. headers: x-request-id: description: >- Aixy request identifier for correlation with Activity and support. schema: type: string example: req_example_01 content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' example: id: chatcmpl_example object: chat.completion created: 0 model: openai/gpt-4.1-mini choices: - index: 0 message: role: assistant content: Hello. finish_reason: stop usage: prompt_tokens: 8 completion_tokens: 2 total_tokens: 10 text/event-stream: schema: type: string description: >- Representative SSE frames. Parse complete events across network chunks. Chat Completions ends with data: [DONE]; Responses uses typed response events. Native provider events and error events are preserved. Usage may arrive only near completion. example: >+ data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":0,"model":"openai/gpt-4.1-mini","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]} data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":0,"model":"openai/gpt-4.1-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} data: [DONE] '400': $ref: '#/components/responses/GatewayError' '401': $ref: '#/components/responses/GatewayError' '403': $ref: '#/components/responses/GatewayError' '404': $ref: '#/components/responses/GatewayError' '408': $ref: '#/components/responses/GatewayError' '413': $ref: '#/components/responses/GatewayError' '424': $ref: '#/components/responses/GatewayError' '429': $ref: '#/components/responses/OpenAIRateLimitError' '500': $ref: '#/components/responses/InferenceInternalError' '502': $ref: '#/components/responses/GatewayError' '503': $ref: '#/components/responses/GatewayError' '504': $ref: '#/components/responses/GatewayError' default: $ref: '#/components/responses/NativeProviderError' security: - GatewayApiKey: [] components: parameters: XRequestId: name: X-Request-ID in: header required: false description: Optional caller-generated request identifier for end-to-end tracing. schema: type: string maxLength: 255 XAixyClient: name: X-Aixy-Client in: header required: false description: >- Optional application[/version] for Activity attribution. Overrides User-Agent detection. Use a product name, not personal data or credentials. Names are 1-64 ASCII letters, digits, spaces, dots, underscores or hyphens, starting with a letter or digit. Optional versions start with a digit and use up to 32 letters, digits, dots, underscores, plus signs or hyphens. Invalid values are ignored. This self-declared label grants no permissions and is not forwarded. schema: type: string maxLength: 97 example: Acme Support/1.2.3 XAixySession: name: X-Aixy-Session in: header required: false description: >- Optional opaque session identifier for virtual routes with session affinity. Scoped to the authenticated caller and alias; never forwarded or recorded. Send full conversation history. Invalid values return 400 when affinity is enabled. Omission retains the route's normal strategy. schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ example: conversation-82 XAixySessionId: name: X-Aixy-Session-ID in: header required: false description: >- Optional opaque conversation identifier recorded in Activity metadata. Reuse it for every call in a conversation. Sessions are isolated by organization, project, user and API key. Use no personal data or secrets. Invalid values are ignored. The header is not forwarded, grants no permissions and does not change routing affinity. schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9._:-]+$ example: conversation-82 XProvider: name: X-Provider in: header required: false description: >- Select a configured provider without changing an unqualified model identifier. A provider-qualified model is preferred for new integrations. schema: type: string schemas: ChatCompletionRequest: type: object required: - model - messages properties: model: type: string description: Provider-qualified or Aixy routing model identifier. example: openai/gpt-4.1-mini messages: type: array minItems: 1 items: $ref: '#/components/schemas/ChatMessage' stream: type: boolean default: false stream_options: type: object properties: include_usage: type: boolean description: Request final stream usage when supported by the provider. additionalProperties: true temperature: type: number top_p: type: number max_tokens: type: integer minimum: 1 description: >- Legacy output-token bound; use the field supported by your selected model. max_completion_tokens: type: integer minimum: 1 description: >- Output-token bound, including reasoning where the provider counts it. stop: oneOf: - type: string - type: array items: type: string tools: type: array items: $ref: '#/components/schemas/ChatTool' tool_choice: oneOf: - type: string enum: - none - auto - required - type: object additionalProperties: true parallel_tool_calls: type: boolean response_format: $ref: '#/components/schemas/ResponseFormat' reasoning_effort: type: - string - 'null' enum: - auto - none - minimal - low - medium - high - xhigh - max - null description: >- Requested reasoning effort. Supported values depend on the destination model. seed: type: integer frequency_penalty: type: number presence_penalty: type: number 'n': type: integer minimum: 1 default: 1 description: >- Translated requests support one completion. Native model limits apply. service_tier: type: - string - 'null' description: >- Provider service tier when supported; also affects pricing attribution. additionalProperties: true ChatCompletionResponse: type: object properties: id: type: string object: type: string example: chat.completion created: type: integer model: type: string choices: type: array items: type: object properties: index: type: integer message: $ref: '#/components/schemas/ChatMessage' finish_reason: type: - string - 'null' additionalProperties: true usage: anyOf: - $ref: '#/components/schemas/TokenUsage' - type: 'null' additionalProperties: true ChatMessage: type: object required: - role description: >- Conversation history, including prior function calls and results. Assistant tool-call messages may omit content or use null. Plaintext reasoning history is accepted on assistant messages but cannot restore opaque provider state. properties: role: type: string enum: - developer - system - user - assistant - tool content: anyOf: - oneOf: - type: string - type: array items: type: object additionalProperties: true - type: 'null' name: type: string tool_call_id: type: string tool_calls: type: array items: $ref: '#/components/schemas/ChatToolCall' reasoning: type: - string - 'null' reasoning_content: type: - string - 'null' allOf: - if: properties: role: enum: - developer - system - user - tool then: required: - content properties: content: oneOf: - type: string - type: array items: type: object additionalProperties: true - if: properties: role: const: tool then: required: - tool_call_id additionalProperties: true ChatTool: type: object required: - type description: >- Function tools work on supported translations; other types require a matching native route. properties: type: type: string example: function function: type: object required: - name properties: name: type: string description: Function name returned to your application. description: type: string parameters: type: object additionalProperties: true description: >- JSON Schema for arguments. Your application executes the function. strict: type: - boolean - 'null' additionalProperties: true additionalProperties: true ResponseFormat: type: object required: - type description: Structured output support depends on the model and provider API. properties: type: type: string enum: - text - json_object - json_schema json_schema: type: object required: - name - schema properties: name: type: string description: type: string strict: type: boolean schema: type: object additionalProperties: true additionalProperties: true additionalProperties: true TokenUsage: type: object properties: prompt_tokens: type: integer minimum: 0 completion_tokens: type: integer minimum: 0 total_tokens: type: integer minimum: 0 additionalProperties: true InferenceErrorResponse: type: object required: - error properties: error: type: object required: - message properties: message: type: string code: type: - string - 'null' type: type: - string - 'null' param: type: - string - integer - 'null' details: type: - object - 'null' additionalProperties: true additionalProperties: true type: type: string request_id: type: string additionalProperties: true AnthropicErrorResponse: type: object required: - type - error properties: type: type: string enum: - error error: type: object required: - type - message properties: type: type: string message: type: string additionalProperties: true request_id: type: string additionalProperties: true ChatToolCall: type: object required: - id - type - function properties: id: type: string type: type: string const: function function: type: object required: - name - arguments properties: name: type: string arguments: type: string description: JSON-encoded function arguments. additionalProperties: true responses: GatewayError: description: >- The gateway or upstream provider rejected the request. Gateway codes identify invalid_request or unsupported_feature (400), invalid_gateway_api_key (401), access or policy denials (403), unavailable models (404), request deadlines (408/504), body limits (413), hard-budget admission failures (424), and upstream or gateway availability failures (502/503). Native provider error details may differ. headers: x-request-id: description: Aixy request identifier for correlation with Activity and support. schema: type: string example: req_example_01 content: application/json: schema: $ref: '#/components/schemas/InferenceErrorResponse' example: error: code: invalid_gateway_api_key message: Gateway API key is invalid or revoked OpenAIRateLimitError: description: >- Aixy or the OpenAI-compatible provider rejected the request because of a rate limit. headers: x-request-id: description: Aixy request identifier for correlation with Activity and support. schema: type: string example: req_example_01 Retry-After: description: >- Optional retry delay. Aixy rate-limit rejections provide a positive delay in seconds; a provider may supply its own Retry-After value, including an HTTP date. required: false schema: type: string example: '60' content: application/json: schema: $ref: '#/components/schemas/InferenceErrorResponse' example: error: code: gateway_rate_limit_exceeded message: The configured rate limit was reached. Retry later. InferenceInternalError: description: >- An internal failure occurred. Some failures return a generic text response; record x-request-id and avoid relying on a JSON body for every server error. headers: x-request-id: description: Aixy request identifier for correlation with Activity and support. schema: type: string example: req_example_01 content: text/plain: schema: type: string example: Internal Server Error application/json: schema: anyOf: - $ref: '#/components/schemas/InferenceErrorResponse' - $ref: '#/components/schemas/AnthropicErrorResponse' NativeProviderError: description: >- A native provider may return another error status and its original payload. After streaming starts, failures can arrive inside the SSE stream instead of changing the HTTP status. Handle both HTTP errors and protocol error events. headers: x-request-id: description: Aixy request identifier for correlation with Activity and support. schema: type: string example: req_example_01 content: application/json: schema: type: object additionalProperties: true securitySchemes: GatewayApiKey: type: http scheme: bearer bearerFormat: gak_… description: >- A project-scoped Aixy API key. Create keys in the dashboard and send the secret as a Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.