openapi.yaml

---
openapi: 3.1.0
info:
  title: Inference Gateway API
  description: |
    The API for interacting with various language models and other AI services.
    OpenAI, Groq, Ollama, and other providers are supported.
    OpenAI compatible API for using with existing clients.
    Unified API for all providers.
  contact:
    name: Inference Gateway
    url: https://inference-gateway.github.io/docs/
  version: 1.0.0
  license:
    name: Apache-2.0
    url: https://github.com/inference-gateway/inference-gateway/blob/main/LICENSE
servers:
  - url: http://localhost:8080
    description: Default server without version prefix for healthcheck and proxy and points
    x-server-tags:
      - Health
      - Proxy
      - MCP
  - url: http://localhost:8080/v1
    description: Default server with version prefix for listing models and chat completions
    x-server-tags:
      - Models
      - Completions
      - Responses
      - Messages
      - Images
      - Audio
      - Videos
      - Metrics
  - url: https://api.inference-gateway.local/v1
    description: Local server with version prefix for listing models and chat completions
    x-server-tags:
      - Models
      - Completions
      - Responses
      - Images
      - Audio
      - Videos
tags:
  - name: Models
    description: List and describe the various models available in the API.
  - name: Completions
    description: Generate completions from the models.
  - name: Responses
    description: Generate model responses using the OpenAI-compatible Responses API.
  - name: Messages
    description: Generate messages using the Anthropic-compatible Messages API.
  - name: Images
    description: Generate images using the OpenAI-compatible Images API.
  - name: Audio
    description: Generate speech audio from text using the OpenAI-compatible Speech API.
  - name: Videos
    description: Generate videos using the OpenAI-compatible Videos API.
  - name: MCP
    description: |
      Model Context Protocol surface. The gateway aggregates every server in
      `MCP_SERVERS` behind a single JSON-RPC endpoint at `POST /mcp`, so an MCP
      client configures one entry and gets the whole fleet.

      Tools are namespaced `mcp_<server alias>_<tool name>` - see the
      `MCPJSONRPCRequest` schema for the naming rules.
  - name: Proxy
    description: Proxy requests to provider endpoints.
  - name: Metrics
    description: Push metrics to the gateway (OTLP/HTTP).
  - name: Health
    description: Health check
paths:
  /models:
    get:
      operationId: listModels
      tags:
        - Models
      description: |
        Lists the currently available models, and provides basic information
        about each one such as the owner and availability.
      summary:
        Lists the currently available models, and provides basic information
        about each one such as the owner and availability.
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to query (optional)
        - name: include
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - context_window
                - modalities
                - pricing
          description: |
            Comma-separated list of metadata keys to include in the response.
            Supported values: `pricing`, `context_window`, `modalities`.
            When omitted, the response remains unchanged (backward compatible).
      responses:
        '200':
          description: List of available models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
              examples:
                allProviders:
                  summary: Models from all providers
                  value:
                    object: 'list'
                    data:
                      - id: 'openai/gpt-4o'
                        object: 'model'
                        created: 1686935002
                        owned_by: 'openai'
                        served_by: 'openai'
                      - id: 'openai/llama-3.3-70b-versatile'
                        object: 'model'
                        created: 1723651281
                        owned_by: 'groq'
                        served_by: 'groq'
                      - id: 'cohere/claude-3-opus-20240229'
                        object: 'model'
                        created: 1708905600
                        owned_by: 'anthropic'
                        served_by: 'anthropic'
                      - id: 'cohere/command-r'
                        object: 'model'
                        created: 1707868800
                        owned_by: 'cohere'
                        served_by: 'cohere'
                      - id: 'ollama/phi3:3.8b'
                        object: 'model'
                        created: 1718441600
                        owned_by: 'ollama'
                        served_by: 'ollama'
                      - id: 'ollama_cloud/gpt-oss:20b'
                        object: 'model'
                        created: 1730419200
                        owned_by: 'ollama_cloud'
                        served_by: 'ollama_cloud'
                      - id: 'mistral/mistral-large-latest'
                        object: 'model'
                        created: 1698019200
                        owned_by: 'mistral'
                        served_by: 'mistral'
                singleProvider:
                  summary: Models from a specific provider
                  value:
                    object: 'list'
                    data:
                      - id: 'openai/gpt-4o'
                        object: 'model'
                        created: 1686935002
                        owned_by: 'openai'
                        served_by: 'openai'
                      - id: 'openai/gpt-4-turbo'
                        object: 'model'
                        created: 1687882410
                        owned_by: 'openai'
                        served_by: 'openai'
                      - id: 'openai/gpt-3.5-turbo'
                        object: 'model'
                        created: 1677649963
                        owned_by: 'openai'
                        served_by: 'openai'
                includePricing:
                  summary: Models with pricing metadata
                  value:
                    object: 'list'
                    data:
                      - id: 'openai/gpt-4o'
                        object: 'model'
                        created: 1686935002
                        owned_by: 'openai'
                        served_by: 'openai'
                        pricing:
                          currency: 'USD'
                          input_per_token: '0.0000025'
                          output_per_token: '0.00001'
                          cache_read_per_token: '0.00000125'
                          cache_write_per_token: '0.0000025'
                          source: 'provider'
                          updated_at: '2025-01-01T00:00:00Z'
                      - id: 'openai/gpt-4-turbo'
                        object: 'model'
                        created: 1687882410
                        owned_by: 'openai'
                        served_by: 'openai'
                        pricing:
                          currency: 'USD'
                          input_per_token: '0.00001'
                          output_per_token: '0.00003'
                          source: 'provider'
                          updated_at: '2025-01-01T00:00:00Z'
                includeContextWindow:
                  summary: Models with context window metadata
                  value:
                    object: 'list'
                    data:
                      - id: 'openai/gpt-4o'
                        object: 'model'
                        created: 1686935002
                        owned_by: 'openai'
                        served_by: 'openai'
                        context_window:
                          tokens: 128000
                          source: 'provider'
                      - id: 'openai/gpt-4-turbo'
                        object: 'model'
                        created: 1687882410
                        owned_by: 'openai'
                        served_by: 'openai'
                        context_window:
                          tokens: 128000
                          source: 'provider'
                includePricingContextWindow:
                  summary: Models with pricing and context window metadata
                  value:
                    object: 'list'
                    data:
                      - id: 'openai/gpt-4o'
                        object: 'model'
                        created: 1686935002
                        owned_by: 'openai'
                        served_by: 'openai'
                        pricing:
                          currency: 'USD'
                          input_per_token: '0.0000025'
                          output_per_token: '0.00001'
                          cache_read_per_token: '0.00000125'
                          cache_write_per_token: '0.0000025'
                          source: 'provider'
                          updated_at: '2025-01-01T00:00:00Z'
                        context_window:
                          tokens: 128000
                          source: 'provider'
                      - id: 'openai/gpt-4-turbo'
                        object: 'model'
                        created: 1687882410
                        owned_by: 'openai'
                        served_by: 'openai'
                        pricing:
                          currency: 'USD'
                          input_per_token: '0.00001'
                          output_per_token: '0.00003'
                          source: 'provider'
                          updated_at: '2025-01-01T00:00:00Z'
                        context_window:
                          tokens: 128000
                          source: 'provider'
                includeModalities:
                  summary: Models with modalities metadata
                  value:
                    object: 'list'
                    data:
                      - id: 'openai/gpt-4o'
                        object: 'model'
                        created: 1686935002
                        owned_by: 'openai'
                        served_by: 'openai'
                        modalities:
                          input:
                            - text
                            - image
                          output:
                            - text
                      - id: 'openai/gpt-image-2'
                        object: 'model'
                        created: 1687882410
                        owned_by: 'openai'
                        served_by: 'openai'
                        modalities:
                          input:
                            - text
                            - image
                          output:
                            - image
        '400':
          description: Bad request - unsupported include value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "Unsupported include value: 'unsupported'. Supported values: pricing, context_window, modalities"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /chat/completions:
    post:
      operationId: createChatCompletion
      tags:
        - Completions
      description: |
        Generates a chat completion based on the provided input.
        The completion can be streamed to the client as it is generated.
      summary: Create a chat completion
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateChatCompletionRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionResponse'
            text/event-stream:
              schema:
                description: |
                  Server-Sent Events stream. Each frame is an `SSEvent` whose
                  `data` field contains the JSON-serialized payload for that
                  event. For content/message chunk events the payload is a
                  `CreateChatCompletionStreamResponse`. The `oneOf` here makes
                  the streaming payload schemas reachable from this operation
                  so that code generators emit types for them.
                oneOf:
                  - $ref: '#/components/schemas/SSEvent'
                  - $ref: '#/components/schemas/CreateChatCompletionStreamResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /responses:
    post:
      operationId: createResponse
      tags:
        - Responses
      description: |
        Creates a model response using the OpenAI-compatible Responses API.
        The request accepts either a single text input or a list of input
        items (allowing batched, multi-turn input in one request), and the
        result can be streamed to the client as it is generated.

        Not every provider implements the Responses API. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message; use `/chat/completions` for those providers.
      summary: Create a model response
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateResponseRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
            text/event-stream:
              schema:
                description: |
                  Server-Sent Events stream. Each frame is an `SSEvent` whose
                  `data` field contains the JSON-serialized payload for that
                  event. For Responses streaming the payload is a
                  `ResponseStreamEvent`. The `oneOf` here makes the streaming
                  payload schemas reachable from this operation so that code
                  generators emit types for them.
                oneOf:
                  - $ref: '#/components/schemas/SSEvent'
                  - $ref: '#/components/schemas/ResponseStreamEvent'
        '400':
          $ref: '#/components/responses/ResponsesNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /messages:
    post:
      operationId: createMessage
      tags:
        - Messages
      description: |
        Creates a message using the Anthropic-compatible Messages API.
        The request follows the Anthropic Messages API format with `model`,
        `max_tokens`, `messages`, optional `system`, `tools`, and streaming
        support.

        Not every provider implements the Messages API. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message; use `/chat/completions` for those providers.
      summary: Create a message
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateMessagesRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagesResponse'
            text/event-stream:
              schema:
                description: |
                  Server-Sent Events stream. Each frame is an `SSEvent` whose
                  `data` field contains the JSON-serialized payload for that
                  event. For Messages streaming the payload is a
                  `MessagesStreamEvent`. The `oneOf` here makes the streaming
                  payload schemas reachable from this operation so that code
                  generators emit types for them.
                oneOf:
                  - $ref: '#/components/schemas/SSEvent'
                  - $ref: '#/components/schemas/MessagesStreamEvent'
        '400':
          $ref: '#/components/responses/MessagesNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /mcp:
    post:
      operationId: mcpJsonRpc
      tags:
        - MCP
      description: |
        JSON-RPC 2.0 endpoint exposing the gateway itself as an MCP server. It
        aggregates every server configured in `MCP_SERVERS` behind one URL, so
        MCP clients (opencode, `infer`, IDE assistants) configure a single entry
        and get the whole fleet, with the gateway's auth, metrics and guardrails
        applied to every tool call.

        The endpoint lives at the root, not under `/v1` - `/v1/*` is the
        OpenAI-compatible surface, MCP is its own protocol and clients expect a
        plain `/mcp`.

        Gated by `MCP_EXPOSE=true` (and `MCP_ENABLED=true`); otherwise the
        gateway answers `403`. Gateway auth is global, so when `AUTH_ENABLE=true`
        this endpoint requires a bearer token like every other route except
        `/health`.

        The endpoint speaks MCP protocol version `2026-07-28` only, over the
        stateless Streamable HTTP transport with `application/json` responses.
        There is no `initialize` handshake and no session: every request carries
        its protocol version in `params._meta["io.modelcontextprotocol/protocolVersion"]`
        (alongside the required `io.modelcontextprotocol/clientInfo` and
        `io.modelcontextprotocol/clientCapabilities`), mirrored in the
        `MCP-Protocol-Version`, `Mcp-Method` and, for `tools/call`, `Mcp-Name`
        headers. `Mcp-Name` may use the `=?base64?<value>?=` encoding.

        Supported methods:

        | Method | Params | Result |
        | --- | --- | --- |
        | `server/discover` | `_meta` only | `DiscoverResult` - `supportedVersions` (`["2026-07-28"]`), `capabilities` (`tools`) |
        | `tools/list` | optional `cursor` | `ListToolsResult` - the aggregated, namespaced tools of every healthy MCP server |
        | `tools/call` | `CallToolRequestParams` (`name`, `arguments`) | `CallToolResult` |

        Every result carries `resultType: "complete"` and identifies the gateway
        in `_meta["io.modelcontextprotocol/serverInfo"]`.

        Param and result shapes are the vendored MCP spec types in
        [`mcp/mcp-schema.yaml`](https://github.com/inference-gateway/schemas/blob/main/mcp/mcp-schema.yaml)
        (`RequestMetaObject`, `DiscoverResult`, `ServerCapabilities`,
        `ListToolsResult`, `CallToolRequestParams`, `CallToolResult`); this spec
        only describes the JSON-RPC envelopes the gateway puts them in.

        `tools/list` tolerates partial availability: when one of the configured
        MCP servers is unreachable its tools are omitted and the healthy servers'
        tools are still returned, rather than failing the whole call. A
        `tools/call` routed to an unavailable server fails with JSON-RPC error
        code `-32603`.

        Errors use JSON-RPC error envelopes:

        | Code | Meaning | HTTP status |
        | --- | --- | --- |
        | `-32020` | header mismatch - a required header is missing, malformed or disagrees with the body; a legacy `initialize` request lands here | `400` |
        | `-32022` | unsupported protocol version; `data` carries `requested` and `supported` | `400` |
        | `-32601` | method not found | `404` |
        | `-32700` | parse error | `200` |
        | `-32600` | invalid request | `200` |
        | `-32602` | invalid params (unknown tool name, bad arguments) | `200` |
        | `-32603` | internal error (upstream MCP server failure) | `200` |

        A request carrying an `Origin` header is rejected with `403`: MCP
        clients are not browsers, and this blocks DNS-rebinding attacks. `GET`
        and `DELETE` answer `405` - there is no standalone stream and no session
        to terminate.
      summary: JSON-RPC 2.0 endpoint for the gateway's MCP server
      security:
        - bearerAuth: []
      parameters:
        - name: MCP-Protocol-Version
          in: header
          required: true
          description: Must equal `params._meta["io.modelcontextprotocol/protocolVersion"]`.
          schema:
            type: string
            example: '2026-07-28'
        - name: Mcp-Method
          in: header
          required: true
          description: Must equal the JSON-RPC `method`.
          schema:
            type: string
            example: 'tools/call'
        - name: Mcp-Name
          in: header
          required: false
          description: |
            Required for `tools/call`; must equal `params.name`. Values that are
            not plain ASCII are sent as `=?base64?<value>?=`.
          schema:
            type: string
            example: 'mcp_deepwiki_ask_question'
      requestBody:
        required: true
        description: A single JSON-RPC 2.0 request or notification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPJSONRPCRequest'
      responses:
        '200':
          description: |
            JSON-RPC response envelope, carrying either a `result` or an `error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPJSONRPCResponse'
        '202':
          description: Notification accepted; no response body
        '400':
          description: |
            Header mismatch (`-32020`) or unsupported protocol version
            (`-32022`), as a JSON-RPC error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPJSONRPCResponse'
        '404':
          description: Method not found (`-32601`), as a JSON-RPC error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPJSONRPCResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MCPNotExposed'
        '500':
          $ref: '#/components/responses/InternalError'
  /.well-known/oauth-protected-resource/mcp:
    get:
      operationId: getMCPProtectedResourceMetadata
      tags:
        - MCP
      description: |
        OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))
        for `POST /mcp`, which MCP `2026-07-28` requires every protected MCP
        server to publish so a client can discover the authorization server on
        its own instead of being handed a pre-configured token.

        Served without a token - it is the one route besides `/health` that
        skips gateway auth, since a client fetches it precisely because it has
        no credentials yet. Every `401` from `POST /mcp` points here through the
        `resource_metadata` parameter of its `WWW-Authenticate` challenge.

        Returns `404` unless `AUTH_ENABLED=true` and the MCP endpoint is exposed
        (`MCP_ENABLED=true` and `MCP_EXPOSE=true`): with no authorization server
        there is nothing to advertise.

        `resource` is `MCP_RESOURCE_URL` when set, and otherwise the request
        scheme (honouring `X-Forwarded-Proto`) and `Host` with `/mcp` appended.
        Behind an ingress that rewrites either, set `MCP_RESOURCE_URL` to the
        canonical public URL clients use.

        Tokens must be issued for that resource (RFC 8707): when the IdP stamps
        the resource indicator into `aud`, list the same value in
        `AUTH_OIDC_AUDIENCE`.
      summary: OAuth 2.0 Protected Resource Metadata for the MCP endpoint
      security: []
      responses:
        '200':
          description: The Protected Resource Metadata document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProtectedResourceMetadata'
              example:
                resource: 'https://gateway.example.com/mcp'
                authorization_servers:
                  - 'https://keycloak.example.com/realms/inference-gateway-realm'
                bearer_methods_supported:
                  - 'header'
        '404':
          $ref: '#/components/responses/NotFound'
  /metrics:
    post:
      operationId: pushMetrics
      tags:
        - Metrics
      description: |
        OTLP/HTTP metrics push endpoint. Accepts an OTLP ExportMetricsServiceRequest
        encoded as protobuf or JSON. Only accessible when TELEMETRY_ENABLED and
        TELEMETRY_METRICS_PUSH_ENABLED are enabled.
      summary: Push metrics to the gateway (OTLP/HTTP)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        description: OTLP ExportMetricsServiceRequest payload
        content:
          application/x-protobuf:
            schema:
              type: string
              format: binary
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OTLP ExportMetricsServiceResponse, possibly with partial success details
          content:
            application/x-protobuf:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Metrics push is not enabled
        '413':
          description: Payload too large
        '415':
          description: Unsupported content type
  /proxy/{provider}/{path}:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Provider'
      - name: path
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type: string
        description: The remaining path to proxy to the provider
    get:
      operationId: proxyGet
      tags:
        - Proxy
      description: |
        Proxy GET request to provider
        The request body depends on the specific provider and endpoint being called.
        If you decide to use this approach, please follow the provider-specific documentations.
      summary: Proxy GET request to provider
      responses:
        '200':
          $ref: '#/components/responses/ProviderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth: []
    post:
      operationId: proxyPost
      tags:
        - Proxy
      description: |
        Proxy POST request to provider
        The request body depends on the specific provider and endpoint being called.
        If you decide to use this approach, please follow the provider-specific documentations.
      summary: Proxy POST request to provider
      requestBody:
        $ref: '#/components/requestBodies/ProviderRequest'
      responses:
        '200':
          $ref: '#/components/responses/ProviderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth: []
    put:
      operationId: proxyPut
      tags:
        - Proxy
      description: |
        Proxy PUT request to provider
        The request body depends on the specific provider and endpoint being called.
        If you decide to use this approach, please follow the provider-specific documentations.
      summary: Proxy PUT request to provider
      requestBody:
        $ref: '#/components/requestBodies/ProviderRequest'
      responses:
        '200':
          $ref: '#/components/responses/ProviderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth: []
    delete:
      operationId: proxyDelete
      tags:
        - Proxy
      description: |
        Proxy DELETE request to provider
        The request body depends on the specific provider and endpoint being called.
        If you decide to use this approach, please follow the provider-specific documentations.
      summary: Proxy DELETE request to provider
      responses:
        '200':
          $ref: '#/components/responses/ProviderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth: []
    patch:
      operationId: proxyPatch
      tags:
        - Proxy
      description: |
        Proxy PATCH request to provider
        The request body depends on the specific provider and endpoint being called.
        If you decide to use this approach, please follow the provider-specific documentations.
      summary: Proxy PATCH request to provider
      requestBody:
        $ref: '#/components/requestBodies/ProviderRequest'
      responses:
        '200':
          $ref: '#/components/responses/ProviderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth: []
  /images/generations:
    post:
      operationId: createImage
      tags:
        - Images
      description: |
        Creates an image given a prompt using the OpenAI-compatible Images API.
        The request returns one or more generated images as URLs or base64-encoded
        JSON data.

        Not every provider implements the Images API. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message; use `/chat/completions` for those providers.
      summary: Create an image
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateImageRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImagesResponse'
        '400':
          $ref: '#/components/responses/ImagesNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /images/edits:
    post:
      operationId: createImageEdit
      tags:
        - Images
      description: |
        Creates an edited or extended image given an original image and a prompt
        using the OpenAI-compatible Images API. The request is sent as
        `multipart/form-data` with the image file as a binary upload.

        Not every provider implements the Images API. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message; use `/chat/completions` for those providers.
      summary: Create an image edit or extension
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateImageEditRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImagesResponse'
        '400':
          $ref: '#/components/responses/ImagesNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /audio/speech:
    post:
      operationId: createSpeech
      tags:
        - Audio
      description: |
        Generates audio from the provided text using the OpenAI-compatible
        Audio API. Mirrors the OpenAI `POST /v1/audio/speech` request body.
        The response is the synthesized audio as raw binary bytes; the actual
        `Content-Type` header of the response reflects the requested
        `response_format` (e.g. `audio/mpeg` for `mp3`).

        Not every provider implements the Audio API. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message; use `/chat/completions` for those providers.
      summary: Generate speech audio from text
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateSpeechRequest'
      responses:
        '200':
          description: |
            The synthesized audio as raw binary bytes. The actual `Content-Type`
            header of the response reflects the requested `response_format`.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/SpeechNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /audio/sfx:
    post:
      operationId: createSFX
      tags:
        - Audio
      description: |
        Generates a non-speech audio clip - a sound effect or ambience - from
        a text prompt. Gateway extension: OpenAI has no sound-effects
        endpoint, so this mirrors the shape of `POST /audio/speech` (JSON in,
        raw audio bytes out) rather than an upstream OpenAI operation. The
        response is the generated audio as raw binary bytes; the actual
        `Content-Type` header of the response reflects the requested
        `response_format` (e.g. `audio/mpeg` for `mp3`).

        Not every provider implements sound-effect generation. Requests routed
        to a provider that does not support it return `400 Bad Request` with an
        explanatory error message.
      summary: Generate a sound effect from a text prompt
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateSFXRequest'
      responses:
        '200':
          description: |
            The generated audio as raw binary bytes. The actual `Content-Type`
            header of the response reflects the requested `response_format`.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/SFXNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /audio/music:
    post:
      operationId: createMusic
      tags:
        - Audio
      description: |
        Composes a music clip from a text prompt. Gateway extension: OpenAI has
        no music endpoint, so this mirrors `POST /audio/sfx` (JSON in, raw
        audio bytes out) rather than an upstream OpenAI operation. The response
        is the generated audio as raw binary bytes; the actual `Content-Type`
        header of the response reflects the requested `response_format` (e.g.
        `audio/mpeg` for `mp3`).

        Not every provider implements music generation. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message.
      summary: Compose a music clip from a text prompt
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateMusicRequest'
      responses:
        '200':
          description: |
            The generated audio as raw binary bytes. The actual `Content-Type`
            header of the response reflects the requested `response_format`.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/MusicNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /videos:
    post:
      operationId: createVideo
      tags:
        - Videos
      description: |
        Creates a video generation job using the OpenAI-compatible Videos API.
        Mirrors the OpenAI `POST /v1/videos` request body. Video generation is
        asynchronous at every provider: this operation returns a `VideoJob`
        immediately, the client polls `GET /videos/{video_id}` until `status`
        is `completed`, then downloads the bytes from
        `GET /videos/{video_id}/content`.

        The request is sent as `multipart/form-data` so reference media can be
        uploaded as binary. The non-standard `audio` field drives a
        talking-avatar render: when present, the model lip-syncs
        `input_reference` to the clip and the video lasts as long as the audio.

        Not every provider implements the Videos API. Requests routed to a
        provider that does not support it return `400 Bad Request` with an
        explanatory error message.
      summary: Create a video generation job
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by model)
      requestBody:
        $ref: '#/components/requestBodies/CreateVideoRequest'
      responses:
        '200':
          description: The created video generation job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJob'
        '400':
          $ref: '#/components/responses/VideosNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /videos/{video_id}:
    get:
      operationId: retrieveVideo
      tags:
        - Videos
      description: |
        Retrieves a video generation job. The gateway keeps no job state, so
        the request is forwarded to the provider that created the job; pass
        `provider` when the job id alone is not enough to route it.
      summary: Retrieve a video generation job
      security:
        - bearerAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
          description: |
            The id of the video generation job, as returned by
            `POST /videos`. Opaque to clients - it may encode the provider -
            and must be sent back verbatim.
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by the job id)
      responses:
        '200':
          description: The video generation job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoJob'
        '400':
          $ref: '#/components/responses/VideosNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /videos/{video_id}/content:
    get:
      operationId: downloadVideoContent
      tags:
        - Videos
      description: |
        Downloads the rendered video of a completed job as raw binary bytes.
        Returns `404` while the job is still `queued` or `in_progress`, or if
        it `failed`.
      summary: Download the rendered video
      security:
        - bearerAuth: []
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
          description: |
            The id of the video generation job, as returned by
            `POST /videos`. Opaque to clients - it may encode the provider -
            and must be sent back verbatim.
        - name: provider
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Provider'
          description: Specific provider to use (default determined by the job id)
      responses:
        '200':
          description: |
            The rendered video as raw binary bytes. The actual `Content-Type`
            header of the response reflects the container produced by the
            provider (e.g. `video/mp4`).
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/VideosNotSupported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /health:
    get:
      operationId: healthCheck
      tags:
        - Health
      description: |
        Health check endpoint
        Returns a 200 status code if the service is healthy
      summary: Health check
      responses:
        '200':
          description: Health check successful
components:
  requestBodies:
    ProviderRequest:
      required: true
      description: |
        ProviderRequest depends on the specific provider and endpoint being called
        If you decide to use this approach, please follow the provider-specific documentations.
      content:
        application/json:
          schema:
            type: object
            properties:
              model:
                type: string
              messages:
                type: array
                items:
                  type: object
                  properties:
                    role:
                      type: string
                    content:
                      type: string
              temperature:
                type: number
                format: float
                default: 0.7
          examples:
            openai:
              summary: OpenAI chat completion request
              value:
                model: 'gpt-3.5-turbo'
                messages:
                  - role: 'user'
                    content: 'Hello! How can I assist you today?'
                temperature: 0.7
            anthropic:
              summary: Anthropic Claude request
              value:
                model: 'claude-3-opus-20240229'
                messages:
                  - role: 'user'
                    content: 'Explain quantum computing'
                temperature: 0.5
            mistral:
              summary: Mistral AI request
              value:
                model: 'mistral-large-latest'
                messages:
                  - role: 'user'
                    content: 'Write a Python function to calculate fibonacci numbers'
                temperature: 0.3
    CreateChatCompletionRequest:
      required: true
      description: |
        ProviderRequest depends on the specific provider and endpoint being called
        If you decide to use this approach, please follow the provider-specific documentations.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateChatCompletionRequest'
    CreateResponseRequest:
      required: true
      description: |
        Request payload for the Responses API. Mirrors the OpenAI
        `POST /v1/responses` request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateResponseRequest'
    CreateMessagesRequest:
      required: true
      description: |
        Request payload for the Messages API. Mirrors the Anthropic
        `POST /v1/messages` request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateMessagesRequest'
    CreateImageRequest:
      required: true
      description: |
        Request payload for the Images API. Mirrors the OpenAI
        `POST /v1/images/generations` request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateImageRequest'
    CreateImageEditRequest:
      required: true
      description: |
        Request payload for the Images Edits API. Mirrors the OpenAI
        `POST /v1/images/edits` request body. Sent as `multipart/form-data`
        with the image file as a binary upload.
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              image:
                type: string
                format: binary
                description: The image to edit. For the GPT image models, a `png`, `webp`, or `jpg` file up to 50MB; for `dall-e-2`, a square PNG under 4MB. If `mask` is not provided, the image must have transparency, which will be used as the mask.
              prompt:
                type: string
                description: A text description of the desired image.
              mask:
                type: string
                format: binary
                description: An additional image whose fully transparent areas (alpha = 0) indicate where the image should be edited. Must be a valid PNG file with the same dimensions as the image (under 4MB for `dall-e-2`).
              model:
                type: string
                description: Model ID to use for image editing.
              n:
                type: integer
                minimum: 1
                maximum: 10
                default: 1
                description: Number of images to generate.
              size:
                $ref: '#/components/schemas/ImageSize'
              quality:
                type: string
                enum:
                  - auto
                  - standard
                  - low
                  - medium
                  - high
                description: |
                  The quality of the edited image. `auto` selects the best
                  quality for the model. The GPT image models support `low`,
                  `medium`, and `high`; `dall-e-2` supports only `standard`.
              response_format:
                type: string
                enum:
                  - url
                  - b64_json
                default: url
                description: The format in which the generated images are returned.
            required:
              - image
              - prompt
    CreateSpeechRequest:
      required: true
      description: |
        Request payload for the Audio API. Mirrors the OpenAI
        `POST /v1/audio/speech` request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSpeechRequest'
    CreateSFXRequest:
      required: true
      description: |
        Request payload for generating a sound effect from a text prompt.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSFXRequest'
    CreateMusicRequest:
      required: true
      description: |
        Request payload for composing a music clip from a text prompt.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateMusicRequest'
    CreateVideoRequest:
      required: true
      description: |
        Request payload for the Videos API. Mirrors the OpenAI
        `POST /v1/videos` request body, sent as `multipart/form-data` with the
        reference media as binary uploads.
      content:
        multipart/form-data:
          schema:
            $ref: '#/components/schemas/CreateVideoRequest'
          encoding:
            reference_images:
              contentType: image/*
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MCPNotExposed:
      description: |
        The MCP surface is not exposed. Both `MCP_ENABLED=true` and
        `MCP_EXPOSE=true` are required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'MCP endpoint is not exposed. Set MCP_EXPOSE=true to enable.'
    ResponsesNotSupported:
      description: |
        The selected provider does not implement the Responses API. The
        gateway returns this when a request is routed to a provider without
        Responses support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'The Responses API is not supported by this provider yet.'
    MessagesNotSupported:
      description: |
        The selected provider does not implement the Messages API. The
        gateway returns this when a request is routed to a provider without
        Messages support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessagesError'
          example:
            type: error
            error:
              type: not_supported_error
              message: 'The Messages API is not supported by this provider yet.'
    ImagesNotSupported:
      description: |
        The selected provider does not implement the Images API. The
        gateway returns this when a request is routed to a provider without
        Images support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'The Images API is not supported by this provider yet.'
    SpeechNotSupported:
      description: |
        The selected provider does not implement the Audio API. The
        gateway returns this when a request is routed to a provider without
        speech synthesis support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'The Audio API is not supported by this provider yet.'
    SFXNotSupported:
      description: |
        The selected provider does not implement sound-effect generation. The
        gateway returns this when a request is routed to a provider without
        text-to-sound-effect support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Sound effect generation is not supported by this provider yet.'
    MusicNotSupported:
      description: |
        The selected provider does not implement music generation. The gateway
        returns this when a request is routed to a provider without
        text-to-music support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Music generation is not supported by this provider yet.'
    VideosNotSupported:
      description: |
        The selected provider does not implement the Videos API. The
        gateway returns this when a request is routed to a provider without
        video generation support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'The Videos API is not supported by this provider yet.'
    ProviderResponse:
      description: |
        ProviderResponse depends on the specific provider and endpoint being called
        If you decide to use this approach, please follow the provider-specific documentations.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProviderSpecificResponse'
          examples:
            openai:
              summary: OpenAI API response
              value:
                {
                  'id': 'chatcmpl-123',
                  'object': 'chat.completion',
                  'created': 1677652288,
                  'model': 'gpt-3.5-turbo',
                  'choices':
                    [
                      {
                        'index': 0,
                        'message':
                          {
                            'role': 'assistant',
                            'content': 'Hello! How can I help you today?',
                          },
                        'finish_reason': 'stop',
                      },
                    ],
                }
            mistral:
              summary: Mistral AI response
              value:
                {
                  'id': 'cmpl-123',
                  'object': 'chat.completion',
                  'created': 1677652288,
                  'model': 'mistral-large-latest',
                  'choices':
                    [
                      {
                        'index': 0,
                        'message':
                          {
                            'role': 'assistant',
                            'content': 'def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)',
                          },
                        'finish_reason': 'stop',
                      },
                    ],
                }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Authentication is optional by default.
        To enable authentication, set AUTH_ENABLED to true.
        When enabled, requests must include a valid JWT token in the Authorization header.
  schemas:
    Provider:
      type: string
      enum:
        - ollama
        - ollama_cloud
        - groq
        - llamacpp
        - openai
        - cloudflare
        - cohere
        - anthropic
        - deepseek
        - elevenlabs
        - google
        - mistral
        - minimax
        - moonshot
        - nvidia
        - zai
      x-provider-configs:
        ollama:
          id: 'ollama'
          url: 'http://ollama:8080/v1'
          auth_type: 'none'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        ollama_cloud:
          id: 'ollama_cloud'
          url: 'https://ollama.com/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        anthropic:
          id: 'anthropic'
          url: 'https://api.anthropic.com/v1'
          auth_type: 'xheader'
          extra_headers:
            anthropic-version: '2023-06-01'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        cohere:
          id: 'cohere'
          url: 'https://api.cohere.ai'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/v1/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/compatibility/v1/chat/completions'
        groq:
          id: 'groq'
          url: 'https://api.groq.com/openai/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        llamacpp:
          id: 'llamacpp'
          url: 'http://llamacpp:8080/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
            speech:
              name: 'create_speech'
              method: 'POST'
              endpoint: '/audio/speech'
        openai:
          id: 'openai'
          url: 'https://api.openai.com/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
            responses:
              name: 'responses'
              method: 'POST'
              endpoint: '/responses'
            images:
              name: 'create_image'
              method: 'POST'
              endpoint: '/images/generations'
            images_edits:
              name: 'create_image_edit'
              method: 'POST'
              endpoint: '/images/edits'
            speech:
              name: 'create_speech'
              method: 'POST'
              endpoint: '/audio/speech'
        cloudflare:
          id: 'cloudflare'
          url: 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/finetunes/public?limit=1000'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/v1/chat/completions'
        deepseek:
          id: 'deepseek'
          url: 'https://api.deepseek.com'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        elevenlabs:
          id: 'elevenlabs'
          url: 'https://api.elevenlabs.io/v1'
          auth_type: 'xheader'
          auth_header: 'xi-api-key'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            speech:
              name: 'create_speech'
              method: 'POST'
              endpoint: '/text-to-speech/{voice}'
            sfx:
              name: 'create_sfx'
              method: 'POST'
              endpoint: '/sound-generation'
            music:
              name: 'create_music'
              method: 'POST'
              endpoint: '/music'
            videos:
              name: 'create_video'
              method: 'POST'
              endpoint: '/flows/video'
            videos_retrieve:
              name: 'retrieve_video'
              method: 'GET'
              endpoint: '/flows/video/{generation_id}'
        google:
          id: 'google'
          url: 'https://generativelanguage.googleapis.com/v1beta/openai'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        mistral:
          id: 'mistral'
          url: 'https://api.mistral.ai/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        minimax:
          id: 'minimax'
          url: 'https://api.minimax.io/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        moonshot:
          id: 'moonshot'
          url: 'https://api.moonshot.ai/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        nvidia:
          id: 'nvidia'
          url: 'https://integrate.api.nvidia.com/v1'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
        zai:
          id: 'zai'
          url: 'https://api.z.ai/api/coding/paas/v4'
          auth_type: 'bearer'
          endpoints:
            models:
              name: 'list_models'
              method: 'GET'
              endpoint: '/models'
            chat:
              name: 'chat_completions'
              method: 'POST'
              endpoint: '/chat/completions'
    ProviderSpecificResponse:
      type: object
      description: |
        Provider-specific response format. Examples:

        OpenAI GET /v1/models?provider=openai response:
        ```json
        {
          "provider": "openai",
          "object": "list",
          "data": [
            {
              "id": "gpt-4",
              "object": "model",
              "created": 1687882410,
              "owned_by": "openai",
              "served_by": "openai"
            }
          ]
        }
        ```

        Anthropic GET /v1/models?provider=anthropic response:
        ```json
        {
          "provider": "anthropic",
          "object": "list",
          "data": [
            {
              "id": "gpt-4",
              "object": "model",
              "created": 1687882410,
              "owned_by": "openai",
              "served_by": "openai"
            }
          ]
        }
        ```
    ProviderAuthType:
      type: string
      description: Authentication type for providers
      enum:
        - bearer
        - xheader
        - query
        - none
    SSEvent:
      type: object
      properties:
        event:
          type: string
          enum:
            - message-start
            - stream-start
            - content-start
            - content-delta
            - content-end
            - message-end
            - stream-end
        data:
          type: string
          format: byte
        retry:
          type: integer
    Endpoints:
      type: object
      properties:
        models:
          type: string
        chat:
          type: string
        responses:
          type: string
        images:
          type: string
        images_edits:
          type: string
        speech:
          type: string
        music:
          type: string
        sfx:
          type: string
          x-go-name: SFX
        videos:
          type: string
        videos_retrieve:
          type: string
      required:
        - models
        - chat
    Error:
      type: object
      properties:
        error:
          type: string
    MessageRole:
      type: string
      description: Role of the message sender
      enum:
        - system
        - user
        - assistant
        - tool
      x-enum-varnames:
        - System
        - User
        - Assistant
        - Tool
    Message:
      type: object
      description: Message structure for provider requests
      properties:
        role:
          $ref: '#/components/schemas/MessageRole'
        content:
          $ref: '#/components/schemas/MessageContent'
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCall'
        tool_call_id:
          type: string
        reasoning_content:
          type: string
          description: The reasoning content of the chunk message.
        reasoning:
          type: string
          description: The reasoning of the chunk message. Same as reasoning_content.
      required:
        - role
        - content
    MessageContent:
      description: Message content - either text or multimodal content parts
      oneOf:
        - type: string
          description: Text content (backward compatibility)
        - type: array
          items:
            $ref: '#/components/schemas/ContentPart'
          description: Array of content parts for multimodal messages
    ContentPart:
      type: object
      description: A content part within a multimodal message
      oneOf:
        - $ref: '#/components/schemas/TextContentPart'
        - $ref: '#/components/schemas/ImageContentPart'
    TextContentPart:
      type: object
      description: Text content part
      properties:
        type:
          type: string
          enum:
            - text
          description: Content type identifier
        text:
          type: string
          description: The text content
      required:
        - type
        - text
    ImageContentPart:
      type: object
      description: Image content part
      properties:
        type:
          type: string
          enum:
            - image_url
          description: Content type identifier
        image_url:
          $ref: '#/components/schemas/ImageURL'
      required:
        - type
        - image_url
    ImageURL:
      type: object
      description: Image URL configuration
      properties:
        url:
          type: string
          description: URL of the image (data URLs supported)
        detail:
          type: string
          enum:
            - auto
            - low
            - high
          x-enum-varnames:
            - ImageURLDetailAuto
            - ImageURLDetailLow
            - ImageURLDetailHigh
          default: auto
          description: Image detail level for vision processing
      required:
        - url
    ImageSize:
      type: string
      description: |
        The size of the generated images. The GPT image models support
        `1024x1024`, `1536x1024`, `1024x1536`, and `auto`; `gpt-image-2`
        also accepts arbitrary `WIDTHxHEIGHT` values such as `1536x864`.
        `dall-e-2` supports `256x256`, `512x512`, and `1024x1024`;
        `dall-e-3` supports `1024x1024`, `1792x1024`, and `1024x1792`.
      enum:
        - auto
        - 256x256
        - 512x512
        - 1024x1024
        - 1536x1024
        - 1024x1536
        - 1792x1024
        - 1024x1792
      x-enum-varnames:
        - ImageSizeAuto
        - ImageSize256x256
        - ImageSize512x512
        - ImageSize1024x1024
        - ImageSize1536x1024
        - ImageSize1024x1536
        - ImageSize1792x1024
        - ImageSize1024x1792
    Image:
      type: object
      description: Represents the url or the content of an image generated by the Images API.
      properties:
        b64_json:
          type: string
          description: |
            The base64-encoded JSON of the generated image, if
            `response_format` is `b64_json`.
        url:
          type: string
          description: |
            The URL of the generated image, if `response_format` is `url`
            (default).
        revised_prompt:
          type: string
          description: |
            The prompt that was used to generate the image, if there was any
            revision to the prompt.
    ImagesResponse:
      type: object
      description: Represents the result of an image generation request.
      properties:
        created:
          type: integer
          format: int64
          description: The Unix timestamp (in seconds) of when the image was created.
        data:
          type: array
          description: The generated images.
          items:
            $ref: '#/components/schemas/Image'
        usage:
          type: object
          description: Usage statistics for the image generation request.
          properties:
            total_tokens:
              type: integer
              format: int64
              default: 0
              description: Total number of tokens used.
            input_tokens:
              type: integer
              format: int64
              default: 0
              description: Number of input tokens.
            output_tokens:
              type: integer
              format: int64
              default: 0
              description: Number of output tokens.
            input_tokens_details:
              type: object
              description: A detailed breakdown of the input tokens.
              properties:
                cached_tokens:
                  type: integer
                  format: int64
                  default: 0
                  description: The number of tokens retrieved from the cache.
      required:
        - created
        - data
    ContextWindow:
      type: object
      description: Context window information for a model
      properties:
        tokens:
          type: integer
          description: Maximum number of tokens the model can process in a single request
        source:
          type: string
          enum:
            - runtime
            - provider
            - community
          x-enum-varnames:
            - ContextWindowSourceRuntime
            - ContextWindowSourceProvider
            - ContextWindowSourceCommunity
          description: Source of the context window information
      required:
        - tokens
        - source
    Pricing:
      type: object
      description: Pricing information for a model
      properties:
        currency:
          type: string
          description: Currency code for the pricing (e.g. USD)
        input_per_token:
          type: string
          description: Price per input token
        output_per_token:
          type: string
          description: Price per output token
        cache_read_per_token:
          type: string
          description: Price per cached input token read
        cache_write_per_token:
          type: string
          description: Price per cached input token write
        source:
          type: string
          enum:
            - provider
            - community
          x-enum-varnames:
            - PricingSourceProvider
            - PricingSourceCommunity
          description: Source of the pricing information
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the pricing was last updated
        subscription:
          type: boolean
          default: false
          description: Model has no per-token price but is gated behind a paid subscription
      required:
        - currency
        - input_per_token
        - output_per_token
        - source
        - updated_at
    Model:
      type: object
      description: Common model information
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
          format: int64
        owned_by:
          type: string
        served_by:
          $ref: '#/components/schemas/Provider'
        modalities:
          oneOf:
            - $ref: '#/components/schemas/ModelModalities'
            - type: 'null'
          description: The input and output modalities of the model (included when `include=modalities`)
        context_window:
          oneOf:
            - $ref: '#/components/schemas/ContextWindow'
            - type: 'null'
          description: Context window information for the model (included when `include=context_window`)
        pricing:
          oneOf:
            - $ref: '#/components/schemas/Pricing'
            - type: 'null'
          description: Pricing information for the model (included when `include=pricing`)
      required:
        - id
        - object
        - created
        - owned_by
        - served_by
    Modality:
      type: string
      description: A single input or output modality
      enum:
        - text
        - image
        - audio
        - video
    ModelModalities:
      type: object
      description: >-
        The input and output modalities of a model, mirroring the models.dev dataset shape.
        Vision models accept `image` in `input`; image-generation models list `image` in
        `output` - when `output` carries `image` but not `text`, the model only generates
        images and cannot chat.
      properties:
        input:
          type: array
          items:
            $ref: '#/components/schemas/Modality'
        output:
          type: array
          items:
            $ref: '#/components/schemas/Modality'
      required:
        - input
        - output
    ListModelsResponse:
      type: object
      description: Response structure for listing models
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
          default: []
      required:
        - object
        - data
    MCPJSONRPCRequest:
      type: object
      description: |
        A JSON-RPC 2.0 request sent to `POST /mcp`, MCP protocol version
        `2026-07-28`. A message without `id` is a notification; this protocol
        version defines none over HTTP, so the gateway acknowledges it with `202`
        and ignores it.

        `params` and the corresponding `result` follow the vendored MCP spec
        types in `mcp/mcp-schema.yaml`. Every request's `params._meta` is a
        `RequestMetaObject` (`io.modelcontextprotocol/protocolVersion`,
        `io.modelcontextprotocol/clientInfo`,
        `io.modelcontextprotocol/clientCapabilities`); `server/discover` takes
        nothing else, `tools/list` takes an optional `cursor` and `tools/call`
        takes `CallToolRequestParams`.

        Tool names are namespaced `mcp_<server alias>_<tool name>`, e.g.
        `mcp_deepwiki_ask_question`. The alias comes from the `alias=url` syntax
        in `MCP_SERVERS` and is derived from the URL host when omitted; it must
        match `^[a-z0-9_-]+$` so the resulting tool name stays valid across all
        LLM providers. The same namespacing applies to the tools injected into
        `/v1/chat/completions`. `mcp_tools_get` and `mcp_tools_execute` are
        reserved for the gateway's own selector meta-tools and cannot be used by
        a configured server.
      properties:
        jsonrpc:
          type: string
          const: '2.0'
          description: JSON-RPC protocol version, always "2.0"
          example: '2.0'
        id:
          description: |
            Request identifier echoed back in the response. Absent for
            notifications.
          oneOf:
            - type: string
            - type: integer
          example: 1
        method:
          type: string
          description: The MCP method to invoke
          enum:
            - server/discover
            - tools/list
            - tools/call
          example: 'tools/call'
        params:
          type: object
          additionalProperties: true
          description: Method parameters, as defined by the MCP specification
          example:
            name: 'mcp_deepwiki_ask_question'
            arguments:
              repoName: 'inference-gateway/inference-gateway'
              question: 'How is MCP wired up?'
            _meta:
              io.modelcontextprotocol/protocolVersion: '2026-07-28'
              io.modelcontextprotocol/clientInfo:
                name: 'opencode'
                version: '1.0.0'
              io.modelcontextprotocol/clientCapabilities: {}
      required:
        - jsonrpc
        - method
    MCPJSONRPCResponse:
      type: object
      description: |
        A JSON-RPC 2.0 response envelope. Exactly one of `result` or `error` is
        present. `result` carries the MCP result type for the requested method
        (`DiscoverResult` for `server/discover`, `ListToolsResult` for
        `tools/list`, `CallToolResult` for `tools/call`) as defined in
        `mcp/mcp-schema.yaml`.
      properties:
        jsonrpc:
          type: string
          const: '2.0'
          description: JSON-RPC protocol version, always "2.0"
          example: '2.0'
        id:
          description: The `id` of the request this responds to
          oneOf:
            - type: string
            - type: integer
          example: 1
        result:
          type: object
          additionalProperties: true
          description: The method result, present on success
        error:
          $ref: '#/components/schemas/MCPJSONRPCError'
      required:
        - jsonrpc
        - id
    MCPJSONRPCError:
      type: object
      description: A JSON-RPC 2.0 error object
      properties:
        code:
          type: integer
          description: |
            JSON-RPC error code: `-32700` parse error, `-32600` invalid request,
            `-32601` method not found, `-32602` invalid params, `-32603` internal
            error (including upstream MCP server failures), `-32001` request
            blocked by guardrails at any phase (`pre_call`, `tool_args`,
            `tool_output`), answered with HTTP `403` and the policy message,
            `-32020` header mismatch, `-32022` unsupported protocol version
            (`data` carries `requested` and `supported`).
          example: -32602
        message:
          type: string
          description: Short description of the error
          example: 'unknown tool: mcp_deepwiki_missing_tool'
        data:
          description: Optional additional error detail
      required:
        - code
        - message
    OAuthProtectedResourceMetadata:
      type: object
      description: |
        OAuth 2.0 Protected Resource Metadata (RFC 9728) for the gateway's MCP
        endpoint. Only the fields a client needs to find the authorization
        server are published.
      properties:
        resource:
          type: string
          description: The canonical public URL of the protected resource
          example: 'https://gateway.example.com/mcp'
        authorization_servers:
          type: array
          items:
            type: string
          description: Issuer identifiers of the authorization servers that mint tokens for this resource
          example:
            - 'https://keycloak.example.com/realms/inference-gateway-realm'
        bearer_methods_supported:
          type: array
          items:
            type: string
          description: How a bearer token may be sent; the gateway reads the Authorization header only
          example:
            - 'header'
      required:
        - resource
        - authorization_servers
        - bearer_methods_supported
    FunctionObject:
      type: object
      properties:
        description:
          type: string
          description:
            A description of what the function does, used by the model to
            choose when and how to call the function.
        name:
          type: string
          description:
            The name of the function to be called. Must be a-z, A-Z, 0-9, or
            contain underscores and dashes, with a maximum length of 64.
        parameters:
          $ref: '#/components/schemas/FunctionParameters'
        strict:
          type: boolean
          default: false
          description:
            Whether to enable strict schema adherence when generating the
            function call. If set to true, the model will follow the exact
            schema defined in the `parameters` field. Only a subset of JSON
            Schema is supported when `strict` is `true`. Learn more about
            Structured Outputs in the [function calling
            guide](docs/guides/function-calling).
      required:
        - name
    ChatCompletionTool:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ChatCompletionToolType'
        function:
          $ref: '#/components/schemas/FunctionObject'
      required:
        - type
        - function
    FunctionParameters:
      type: object
      description: >-
        The parameters the functions accepts, described as a JSON Schema object.
        See the [guide](/docs/guides/function-calling) for examples, and the
        [JSON Schema
        reference](https://json-schema.org/understanding-json-schema/) for
        documentation about the format. 

        Omitting `parameters` defines a function with an empty parameter list.
      additionalProperties: true
    ChatCompletionToolType:
      type: string
      description: The type of the tool. Currently, only `function` is supported.
      enum:
        - function
    CompletionUsage:
      type: object
      description: Usage statistics for the completion request.
      properties:
        completion_tokens:
          type: integer
          default: 0
          format: int64
          description: Number of tokens in the generated completion.
        prompt_tokens:
          type: integer
          default: 0
          format: int64
          description: Number of tokens in the prompt.
        total_tokens:
          type: integer
          default: 0
          format: int64
          description: Total number of tokens used in the request (prompt + completion).
        completion_tokens_details:
          type: object
          description: Breakdown of tokens used in a completion.
          properties:
            accepted_prediction_tokens:
              type: integer
              default: 0
              format: int64
              description: When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion.
            audio_tokens:
              type: integer
              default: 0
              format: int64
              description: Audio input tokens generated by the model.
            reasoning_tokens:
              type: integer
              default: 0
              format: int64
              description: Tokens generated by the model for reasoning.
            rejected_prediction_tokens:
              type: integer
              default: 0
              format: int64
              description: When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits.
        prompt_tokens_details:
          type: object
          description: Breakdown of tokens used in the prompt.
          properties:
            audio_tokens:
              type: integer
              default: 0
              format: int64
              description: Audio input tokens present in the prompt.
            cached_tokens:
              type: integer
              default: 0
              format: int64
              description: Cached tokens present in the prompt.
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
    ChatCompletionStreamOptions:
      description: >
        Options for streaming response. Only set this when you set `stream:
        true`.
      type: object
      properties:
        include_usage:
          type: boolean
          description: >
            If set, an additional chunk will be streamed before the `data:
            [DONE]` message. The `usage` field on this chunk shows the token
            usage statistics for the entire request, and the `choices` field
            will always be an empty array. All other chunks will also include a
            `usage` field, but with a null value.
      required:
        - include_usage
    CreateChatCompletionRequest:
      type: object
      properties:
        model:
          type: string
          description: Model ID to use
        messages:
          description: >
            A list of messages comprising the conversation so far.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Message'
        max_tokens:
          description: >
            The maximum number of tokens that can be generated in the chat
            completion. This value can be used to control costs for text
            generated via API. This value is now deprecated in favor of
            `max_completion_tokens`, and is not compatible with o-series models.
          type: integer
          deprecated: true
        max_completion_tokens:
          description: >
            An upper bound for the number of tokens that can be generated
            for a completion, including visible output tokens and reasoning tokens.
          type: integer
        temperature:
          description: >
            What sampling temperature to use, between 0 and 2. Higher values
            like 0.8 will make the output more random, while lower values
            like 0.2 will make it more focused and deterministic.
          type: number
          minimum: 0
          maximum: 2
          default: 1
        top_p:
          description: >
            An alternative to sampling with temperature, called nucleus
            sampling, where the model considers the results of the tokens
            with top_p probability mass.
          type: number
          minimum: 0
          maximum: 1
          default: 1
        frequency_penalty:
          description: >
            Number between -2.0 and 2.0. Positive values penalize new tokens
            based on their existing frequency in the text so far, decreasing
            the model's likelihood to repeat the same line verbatim.
          type: number
          minimum: -2
          maximum: 2
          default: 0
        presence_penalty:
          description: >
            Number between -2.0 and 2.0. Positive values penalize new tokens
            based on whether they appear in the text so far, increasing the
            model's likelihood to talk about new topics.
          type: number
          minimum: -2
          maximum: 2
          default: 0
        n:
          description: >
            How many chat completion choices to generate for each input message.
          type: integer
          minimum: 1
          maximum: 128
          default: 1
        stop:
          description: >
            Up to 4 sequences where the API will stop generating further tokens.
          oneOf:
            - type: string
            - type: array
              minItems: 1
              maxItems: 4
              items:
                type: string
        seed:
          description: >
            If specified, our system will make a best effort to sample
            deterministically, such that repeated requests with the same `seed`
            and parameters should return the same result. Determinism is not
            guaranteed, and you should refer to the `system_fingerprint`
            response parameter to monitor changes in the backend.
          type: integer
        logprobs:
          description: >
            Whether to return log probabilities of the output tokens or not. If
            true, returns the log probabilities of each output token returned in
            the `content` of `message`.
          type: boolean
          default: false
        top_logprobs:
          description: >
            An integer between 0 and 20 specifying the number of most likely
            tokens to return at each token position, each with an associated log
            probability. `logprobs` must be set to `true` if this parameter is
            used.
          type: integer
          minimum: 0
          maximum: 20
        response_format:
          description: >
            An object specifying the format that the model must output. Setting
            to `{ "type": "json_schema", "json_schema": {...} }` enables
            Structured Outputs which guarantees the model will match your
            supplied JSON schema. Setting to `{ "type": "json_object" }` enables
            the older JSON mode, which ensures the message the model generates is
            valid JSON.
          oneOf:
            - $ref: '#/components/schemas/ResponseFormatText'
            - $ref: '#/components/schemas/ResponseFormatJsonSchema'
            - $ref: '#/components/schemas/ResponseFormatJsonObject'
        logit_bias:
          description: >
            Modify the likelihood of specified tokens appearing in the
            completion. Accepts a JSON object that maps tokens (specified by
            their token ID in the tokenizer) to an associated bias value from
            -100 to 100. The bias is added to the logits generated by the model
            prior to sampling.
          type: object
          additionalProperties:
            type: integer
        user:
          description: >
            A unique identifier representing your end-user, which can help to
            monitor and detect abuse.
          type: string
        stream:
          description: >
            If set to true, the model response data will be streamed to the
            client as it is generated using [server-sent
            events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
          type: boolean
          default: false
        stream_options:
          $ref: '#/components/schemas/ChatCompletionStreamOptions'
        tools:
          type: array
          description: >
            A list of tools the model may call. Currently, only functions
            are supported as a tool. Use this to provide a list of functions
            the model may generate JSON inputs for. A max of 128 functions
            are supported.
          items:
            $ref: '#/components/schemas/ChatCompletionTool'
        tool_choice:
          $ref: '#/components/schemas/ChatCompletionToolChoiceOption'
        parallel_tool_calls:
          type: boolean
          default: true
          description: >
            Whether to enable parallel function calling during tool use.
        reasoning_format:
          type: string
          description: >
            The format of the reasoning content. Can be `raw` or `parsed`.

            When specified as raw some reasoning models will output <think /> tags.
            When specified as parsed the model will output the reasoning under
            `reasoning` or `reasoning_content` attribute.
        reasoning_effort:
          type: string
          description: >
            Constrains effort on reasoning for reasoning models. Currently
            supported values are `minimal`, `low`, `medium`, and `high`.
            Reducing reasoning effort can result in faster responses and fewer
            tokens used on reasoning in a response.
          x-enum-varnames:
            - Minimal
            - Low
            - Medium
            - High
          enum:
            - minimal
            - low
            - medium
            - high
      required:
        - model
        - messages
    ResponseFormatText:
      type: object
      description: Default response format. Used to generate text responses.
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `text`.
          enum:
            - text
      required:
        - type
    ResponseFormatJsonObject:
      type: object
      description: >
        JSON object response format. An older method of generating JSON
        responses. Using `json_schema` is recommended for models that support
        it. Note that the model will not generate JSON without a system or user
        message instructing it to do so.
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `json_object`.
          enum:
            - json_object
      required:
        - type
    ResponseFormatJsonSchema:
      type: object
      description: >
        JSON Schema response format. Used to generate structured JSON responses.
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `json_schema`.
          enum:
            - json_schema
        json_schema:
          type: object
          description: Structured Outputs configuration options, including a JSON Schema.
          properties:
            description:
              type: string
              description: >
                A description of what the response format is for, used by the
                model to determine how to respond in the format.
            name:
              type: string
              description: >
                The name of the response format. Must be a-z, A-Z, 0-9, or
                contain underscores and dashes, with a maximum length of 64.
            schema:
              $ref: '#/components/schemas/ResponseFormatJsonSchemaSchema'
            strict:
              type: boolean
              default: false
              description: >
                Whether to enable strict schema adherence when generating the
                output. If set to true, the model will always follow the exact
                schema defined in the `schema` field. Only a subset of JSON
                Schema is supported when `strict` is `true`.
          required:
            - name
      required:
        - type
        - json_schema
    ResponseFormatJsonSchemaSchema:
      type: object
      description: >
        The schema for the response format, described as a JSON Schema object.
      additionalProperties: true
    ChatCompletionToolChoiceOption:
      description: >
        Controls which (if any) tool is called by the model. `none` means the
        model will not call any tool and instead generates a message. `auto`
        means the model can pick between generating a message or calling one or
        more tools. `required` means the model must call one or more tools.
        Specifying a particular tool via `{"type": "function", "function":
        {"name": "my_function"}}` forces the model to call that tool.

        `none` is the default when no tools are present. `auto` is the default
        if tools are present.
      oneOf:
        - type: string
          description: >
            `none` means the model will not call any tool and instead generates
            a message. `auto` means the model can pick between generating a
            message or calling one or more tools. `required` means the model
            must call one or more tools.
          enum:
            - none
            - auto
            - required
        - $ref: '#/components/schemas/ChatCompletionNamedToolChoice'
    ChatCompletionNamedToolChoice:
      type: object
      description: >
        Specifies a tool the model should use. Use to force the model to call a
        specific function.
      properties:
        type:
          $ref: '#/components/schemas/ChatCompletionToolType'
        function:
          type: object
          properties:
            name:
              type: string
              description: The name of the function to call.
          required:
            - name
      required:
        - type
        - function
    ChatCompletionMessageToolCallFunction:
      type: object
      description: The function that the model called.
      properties:
        name:
          type: string
          description: The name of the function to call.
        arguments:
          type: string
          description:
            The arguments to call the function with, as generated by the model
            in JSON format. Note that the model does not always generate
            valid JSON, and may hallucinate parameters not defined by your
            function schema. Validate the arguments in your code before
            calling your function.
      required:
        - name
        - arguments
    ChatCompletionMessageToolCall:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tool call.
        type:
          $ref: '#/components/schemas/ChatCompletionToolType'
        function:
          $ref: '#/components/schemas/ChatCompletionMessageToolCallFunction'
        extra_content:
          $ref: '#/components/schemas/ToolCallExtraContent'
      required:
        - id
        - type
        - function
    ChatCompletionChoice:
      type: object
      properties:
        finish_reason:
          $ref: '#/components/schemas/FinishReason'
        index:
          type: integer
          description: The index of the choice in the list of choices.
        message:
          $ref: '#/components/schemas/Message'
        logprobs:
          description: Log probability information for the choice.
          type: object
          nullable: true
          properties:
            content:
              description: A list of message content tokens with log probability information.
              type: array
              items:
                $ref: '#/components/schemas/ChatCompletionTokenLogprob'
            refusal:
              description: A list of message refusal tokens with log probability information.
              type: array
              items:
                $ref: '#/components/schemas/ChatCompletionTokenLogprob'
          required:
            - content
            - refusal
      required:
        - finish_reason
        - index
        - message
    ChatCompletionStreamChoice:
      type: object
      required:
        - delta
        - finish_reason
        - index
      properties:
        delta:
          $ref: '#/components/schemas/ChatCompletionStreamResponseDelta'
        logprobs:
          description: Log probability information for the choice.
          type: object
          properties:
            content:
              description: A list of message content tokens with log probability information.
              type: array
              items:
                $ref: '#/components/schemas/ChatCompletionTokenLogprob'
            refusal:
              description: A list of message refusal tokens with log probability information.
              type: array
              items:
                $ref: '#/components/schemas/ChatCompletionTokenLogprob'
          required:
            - content
            - refusal
        finish_reason:
          $ref: '#/components/schemas/FinishReason'
        index:
          type: integer
          description: The index of the choice in the list of choices.
    CreateChatCompletionResponse:
      type: object
      description:
        Represents a chat completion response returned by model, based on
        the provided input.
      properties:
        id:
          type: string
          description: A unique identifier for the chat completion.
        choices:
          type: array
          description:
            A list of chat completion choices. Can be more than one if `n` is
            greater than 1.
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        created:
          type: integer
          description:
            The Unix timestamp (in seconds) of when the chat completion was
            created.
        model:
          type: string
          description: The model used for the chat completion.
        object:
          type: string
          description: The object type, which is always `chat.completion`.
          x-stainless-const: true
        usage:
          $ref: '#/components/schemas/CompletionUsage'
      required:
        - choices
        - created
        - id
        - model
        - object
    ChatCompletionStreamResponseDelta:
      type: object
      description: A chat completion delta generated by streamed model responses.
      properties:
        content:
          type: string
          description: The contents of the chunk message.
        reasoning_content:
          type: string
          description: The reasoning content of the chunk message.
        reasoning:
          type: string
          description: The reasoning of the chunk message. Same as reasoning_content.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionMessageToolCallChunk'
        role:
          $ref: '#/components/schemas/MessageRole'
        refusal:
          type: string
          description: The refusal message generated by the model.
      required:
        - content
        - role
    ChatCompletionMessageToolCallChunk:
      type: object
      properties:
        index:
          type: integer
        id:
          type: string
          description: The ID of the tool call.
        type:
          type: string
          description: The type of the tool. Currently, only `function` is supported.
        function:
          $ref: '#/components/schemas/ChatCompletionMessageToolCallFunction'
        extra_content:
          $ref: '#/components/schemas/ToolCallExtraContent'
      required:
        - index
    ToolCallExtraContent:
      type: object
      description: |
        Provider-specific opaque data attached to a tool call. The contents are
        not interpreted by the gateway, but must be echoed back verbatim on the
        next request that references this tool call. Currently used by Google
        Gemini extended-thinking models to carry the per-call `thought_signature`.
        Other providers may ignore the field.
      properties:
        google:
          type: object
          description: Google Gemini-specific extra content.
          properties:
            thought_signature:
              type: string
              description: |
                Opaque signature returned with reasoning-enabled tool calls.
                Must be echoed back verbatim in the next request that includes
                this tool call, or Google will reject the request.
          additionalProperties: true
    ChatCompletionTokenLogprob:
      type: object
      properties:
        token: &a1
          description: The token.
          type: string
        logprob: &a2
          description:
            The log probability of this token, if it is within the top 20 most
            likely tokens. Otherwise, the value `-9999.0` is used to signify
            that the token is very unlikely.
          type: number
        bytes: &a3
          description:
            A list of integers representing the UTF-8 bytes representation of
            the token. Useful in instances where characters are represented by
            multiple tokens and their byte representations must be combined to
            generate the correct text representation. Can be `null` if there is
            no bytes representation for the token.
          type: array
          items:
            type: integer
        top_logprobs:
          description:
            List of the most likely tokens and their log probability, at this
            token position. In rare cases, there may be fewer than the number of
            requested `top_logprobs` returned.
          type: array
          items:
            type: object
            properties:
              token: *a1
              logprob: *a2
              bytes: *a3
            required:
              - token
              - logprob
              - bytes
      required:
        - token
        - logprob
        - bytes
        - top_logprobs
    FinishReason:
      type: string
      description: >
        The reason the model stopped generating tokens. This will be
        `stop` if the model hit a natural stop point or a provided
        stop sequence,

        `length` if the maximum number of tokens specified in the
        request was reached,

        `content_filter` if content was omitted due to a flag from our
        content filters,

        `tool_calls` if the model called a tool.
      enum:
        - stop
        - length
        - tool_calls
        - content_filter
        - function_call
      x-enum-varnames:
        - Stop
        - Length
        - ToolCalls
        - ContentFilter
        - FunctionCall
    CreateChatCompletionStreamResponse:
      type: object
      description: |
        Represents a streamed chunk of a chat completion response returned
        by the model, based on the provided input.
      properties:
        id:
          type: string
          description:
            A unique identifier for the chat completion. Each chunk has the
            same ID.
        choices:
          type: array
          description: >
            A list of chat completion choices. Can contain more than one
            elements if `n` is greater than 1. Can also be empty for the

            last chunk if you set `stream_options: {"include_usage": true}`.
          items:
            $ref: '#/components/schemas/ChatCompletionStreamChoice'
        created:
          type: integer
          description:
            The Unix timestamp (in seconds) of when the chat completion was
            created. Each chunk has the same timestamp.
        model:
          type: string
          description: The model to generate the completion.
        system_fingerprint:
          type: string
          description: >
            This fingerprint represents the backend configuration that the model
            runs with.

            Can be used in conjunction with the `seed` request parameter to
            understand when backend changes have been made that might impact
            determinism.
        object:
          type: string
          description: The object type, which is always `chat.completion.chunk`.
        usage:
          $ref: '#/components/schemas/CompletionUsage'
        reasoning_format:
          type: string
          description: >
            The format of the reasoning content. Can be `raw` or `parsed`.

            When specified as raw some reasoning models will output <think /> tags.
            When specified as parsed the model will output the reasoning under reasoning_content.
      required:
        - choices
        - created
        - id
        - model
        - object
    CreateImageRequest:
      type: object
      description: |
        Request body for creating an image via the OpenAI-compatible Images API.
      properties:
        prompt:
          type: string
          description: A text description of the desired image.
        model:
          type: string
          description: Model ID to use for image generation.
        n:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: Number of images to generate.
        size:
          $ref: '#/components/schemas/ImageSize'
        quality:
          type: string
          enum:
            - auto
            - standard
            - hd
            - low
            - medium
            - high
          description: |
            The quality of the image. `auto` selects the best quality for
            the model. The GPT image models support `low`, `medium`, and
            `high`; `dall-e-3` supports `standard` and `hd`; `dall-e-2`
            supports only `standard`.
        response_format:
          type: string
          enum:
            - url
            - b64_json
          default: url
          description: |
            The format in which the generated images are returned. Must be
            one of `url` or `b64_json`.
      required:
        - prompt
    CreateSpeechRequest:
      type: object
      description: |
        Request body for generating speech audio via the OpenAI-compatible
        Audio API.
      properties:
        model:
          type: string
          description: Model ID to use for speech synthesis (e.g. `gpt-4o-mini-tts` or `tts-1`).
        input:
          type: string
          maxLength: 4096
          description: The text to synthesize into audio (4096 characters maximum).
        instructions:
          type: string
          maxLength: 4096
          description: >
            Control the voice of your generated audio with additional
            instructions. Does not work with `tts-1` or `tts-1-hd`.
        voice:
          type: string
          description: |-
            The voice to use when generating the audio. OpenAI built-in voices
            are `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`,
            `nova`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. Other
            providers accept their own voice identifiers - for ElevenLabs this
            is a voice id, including the id of a previously cloned voice.
        response_format:
          type: string
          enum:
            - mp3
            - opus
            - aac
            - flac
            - wav
            - pcm
          default: mp3
          description: The audio format of the response.
        speed:
          type: number
          minimum: 0.25
          maximum: 4
          default: 1
          description: The speed of the generated audio.
        language:
          type: string
          pattern: '^[a-z]{2}$'
          default: en
          description: |-
            ISO 639-1 code for the language of the generated speech.
            Non-standard extension: OpenAI's speech API has no language field
            (the name matches its transcription API). Forwarded to the
            provider as-is; the gateway's built-in local engine
            (`local/qwen3-tts`) supports `zh`, `en`, `de`, `it`, `pt`, `es`,
            `ja`, `ko`, `fr` and `ru`, and rejects other codes.
        reference_audio:
          type: string
          format: byte
          description: |-
            Base64-encoded audio sample for zero-shot voice cloning. The
            generated speech mimics the voice in the sample. Best results with
            a clean mono recording between 1 and 30 seconds; WAV is the safest
            container. Forwarded to the provider as-is - only providers with
            voice-cloning support honor it (e.g. Qwen3-TTS-compatible
            backends); others ignore or reject it. Not supported by OpenAI.
      required:
        - model
        - input
        - voice
    CreateSFXRequest:
      type: object
      description: |
        Request body for generating a non-speech audio clip - a sound effect
        or ambience - from a text prompt.
      properties:
        model:
          type: string
          description: Model ID to use for sound-effect generation (e.g. `elevenlabs/eleven_text_to_sound_v2`).
        prompt:
          type: string
          description: Description of the sound to generate (e.g. `distant thunder rolling over a valley`).
        duration_seconds:
          type: number
          minimum: 0.5
          maximum: 30
          description: |-
            Length of the generated clip in seconds. Omit to let the provider
            pick a length that fits the prompt.
        prompt_influence:
          type: number
          minimum: 0
          maximum: 1
          description: |-
            How closely the generation follows the prompt. Higher values stay
            closer to the prompt, lower values allow more variation. Omit to
            use the provider default.
        loop:
          type: boolean
          description: Whether to generate a clip that loops seamlessly.
        response_format:
          type: string
          enum:
            - mp3
            - opus
            - aac
            - flac
            - pcm
          default: mp3
          description: The audio format of the response.
      required:
        - model
        - prompt
    CreateMusicRequest:
      type: object
      description: |
        Request body for composing a music clip from a text prompt.
      properties:
        model:
          type: string
          description: Model ID to use for music generation (e.g. `elevenlabs/music_v2_5`).
        prompt:
          type: string
          description: Description of the music to compose - genre, mood, instruments, tempo.
        duration_seconds:
          type: number
          minimum: 3
          maximum: 600
          description: |-
            Length of the clip in seconds. Omit to let the provider pick a
            length that fits the prompt.
        instrumental:
          type: boolean
          default: false
          description: Guarantee the generated clip has no vocals.
        response_format:
          type: string
          enum:
            - mp3
            - opus
            - aac
            - flac
            - pcm
          default: mp3
          description: The audio format of the response.
      required:
        - model
        - prompt
    CreateVideoRequest:
      type: object
      description: |
        Request body for creating a video generation job via the
        OpenAI-compatible Videos API. Sent as `multipart/form-data`.
      properties:
        model:
          type: string
          description: Model ID to use for video generation (e.g. `elevenlabs/creatify-aurora`).
        prompt:
          type: string
          description: |-
            Text description of the video to generate. Optional for
            audio-driven avatar models, where the dialogue comes from `audio`
            and the prompt only describes framing, never the spoken words.
        input_reference:
          type: string
          format: binary
          description: |-
            Optional image used as the first frame or, for avatar models, the
            portrait to animate.
        reference_images:
          type: array
          items:
            type: string
            format: binary
          description: |-
            Non-standard extension (OpenAI's Videos API has no reference-images
            field): optional reference images of the subject (e.g. the same
            person from several angles), sent as repeated `reference_images`
            parts. Used by providers that keep a character consistent across
            shots (e.g. ElevenLabs `veo-3.1-*`, `bytedance-seedance-v2*`).
            Distinct from `input_reference`, which stays the first frame or,
            for avatar models, the portrait to animate - avatar models ignore
            this field. Providers without reference-image support ignore or
            reject it.
        audio:
          type: string
          format: binary
          description: |-
            Non-standard extension (OpenAI's Videos API has no audio field):
            an audio clip - `audio/wav` or `audio/mpeg` - that drives the
            render. When present, the model lip-syncs `input_reference` to it
            and the generated video lasts as long as the clip, so `seconds` is
            ignored. Forwarded to the provider as-is; only providers with
            talking-avatar support honor it (e.g. ElevenLabs
            `creatify-aurora`), others ignore or reject it.
        seconds:
          type: string
          description: |-
            Requested duration of the generated video in seconds, as a string
            (e.g. `4`, `8`, `12`). Providers accept a limited set of values;
            omit to use the provider default. Ignored when `audio` is present.
        size:
          type: string
          description: |-
            Requested output resolution as `widthxheight` (e.g. `720x1280`).
            Providers accept a limited set of values - ElevenLabs
            `creatify-aurora` maps to `480p` and `720p`. Omit to use the
            provider default.
      required:
        - model
    VideoJob:
      type: object
      description: |
        A video generation job. Returned by `POST /videos` and
        `GET /videos/{video_id}`.
      properties:
        id:
          type: string
          description: |-
            Identifier of the video generation job. Opaque to clients - it may
            encode the provider - and must be sent back verbatim to
            `GET /videos/{video_id}`.
        object:
          type: string
          const: video
          description: The object type, which is always `video`.
        model:
          type: string
          description: The model used to generate the video.
        status:
          type: string
          enum:
            - queued
            - in_progress
            - completed
            - failed
          description: Current status of the job.
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Completion percentage of the render.
        created_at:
          type: integer
          description: Unix timestamp (in seconds) of when the job was created.
        completed_at:
          type: integer
          nullable: true
          description: Unix timestamp (in seconds) of when the job finished, null while it is still running.
        seconds:
          type: string
          description: Duration of the generated video in seconds, as a string.
        size:
          type: string
          description: Resolution of the generated video as `widthxheight`.
        error:
          type: object
          nullable: true
          description: The error that caused the job to fail, null otherwise.
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
      required:
        - id
        - object
        - model
        - status
        - created_at
    CreateResponseRequest:
      type: object
      description: |
        Request body for creating a model response via the Responses API.
      properties:
        model:
          type: string
          description: Model ID used to generate the response.
        input:
          $ref: '#/components/schemas/ResponseInput'
        instructions:
          type: string
          nullable: true
          description: >
            A system (or developer) message inserted into the model's context.
            When used with `previous_response_id`, instructions from previous
            responses are not carried over.
        max_output_tokens:
          type: integer
          nullable: true
          description: >
            An upper bound for the number of tokens that can be generated for a
            response, including visible output tokens and reasoning tokens.
        stream:
          type: boolean
          default: false
          description: >
            If set to true, the model response data is streamed to the client
            as it is generated using
            [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
        temperature:
          type: number
          format: float
          nullable: true
          default: 1
          description: >
            What sampling temperature to use, between 0 and 2. Higher values
            make the output more random; lower values make it more focused.
        top_p:
          type: number
          format: float
          nullable: true
          default: 1
          description: >
            An alternative to sampling with temperature, called nucleus
            sampling, where the model considers the tokens with `top_p`
            probability mass.
        tools:
          type: array
          description: >
            An array of tools the model may call while generating a response.
          items:
            $ref: '#/components/schemas/ResponseTool'
        tool_choice:
          $ref: '#/components/schemas/ResponseToolChoice'
        reasoning:
          $ref: '#/components/schemas/ResponseReasoning'
        text:
          $ref: '#/components/schemas/ResponseTextConfig'
        previous_response_id:
          type: string
          nullable: true
          description: >
            The unique ID of the previous response to the model. Use this to
            create multi-turn conversations.
        store:
          type: boolean
          default: true
          description: >
            Whether to store the generated model response for later retrieval.
        background:
          type: boolean
          default: false
          description: >
            Whether to run the model response in the background. Useful for
            long-running or batched requests.
        parallel_tool_calls:
          type: boolean
          default: true
          description: Whether to allow the model to run tool calls in parallel.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >
            Set of up to 16 key-value pairs that can be attached to the object
            and returned when retrieving the response.
        user:
          type: string
          description: >
            A stable identifier for your end-users, used to help detect and
            prevent abuse.
      required:
        - model
        - input
    ResponseInput:
      description: >
        Text, image, or file inputs to the model. Either a single text prompt
        or a list of input items representing a (possibly batched) conversation.
      oneOf:
        - type: string
          description: A text input to the model, equivalent to a user message.
        - type: array
          description: A list of input items.
          items:
            $ref: '#/components/schemas/ResponseInputItem'
    ResponseInputItem:
      type: object
      description: >
        A single input item. Most commonly an input message with a role and
        content.
      properties:
        type:
          type: string
          default: message
          description: The type of the input item. Defaults to `message`.
        role:
          $ref: '#/components/schemas/ResponseRole'
        content:
          $ref: '#/components/schemas/ResponseInputMessageContent'
      required:
        - role
        - content
    ResponseRole:
      type: string
      description: The role of the message input.
      enum:
        - user
        - assistant
        - system
        - developer
      x-enum-varnames:
        - ResponseRoleUser
        - ResponseRoleAssistant
        - ResponseRoleSystem
        - ResponseRoleDeveloper
    ResponseInputMessageContent:
      description: >
        Text or multimodal content for an input message. Either a string or a
        list of content parts.
      oneOf:
        - type: string
          description: A text input to the model.
        - type: array
          items:
            $ref: '#/components/schemas/ResponseInputContentPart'
    ResponseInputContentPart:
      type: object
      description: A content part within an input message.
      oneOf:
        - $ref: '#/components/schemas/ResponseInputText'
        - $ref: '#/components/schemas/ResponseInputImage'
    ResponseInputText:
      type: object
      description: A text input to the model.
      properties:
        type:
          type: string
          enum:
            - input_text
          description: The type of the input item. Always `input_text`.
        text:
          type: string
          description: The text input to the model.
      required:
        - type
        - text
    ResponseInputImage:
      type: object
      description: An image input to the model.
      properties:
        type:
          type: string
          enum:
            - input_image
          description: The type of the input item. Always `input_image`.
        image_url:
          type: string
          description: The URL of the image (data URLs supported).
        detail:
          type: string
          enum:
            - auto
            - low
            - high
          x-enum-varnames:
            - ResponseInputImageDetailAuto
            - ResponseInputImageDetailLow
            - ResponseInputImageDetailHigh
          default: auto
          description: The detail level of the image to send to the model.
      required:
        - type
    ResponseTool:
      type: object
      description: >
        A tool the model may call. Only function tools are modeled here. Note
        the Responses API uses a flattened function tool shape (`name`,
        `description`, and `parameters` at the top level) rather than nesting
        them under a `function` object as `/chat/completions` does.
      properties:
        type:
          type: string
          enum:
            - function
          x-enum-varnames:
            - ResponseToolTypeFunction
          description: The type of the tool. Currently only `function`.
        name:
          type: string
          description: The name of the function to call.
        description:
          type: string
          description: >
            A description of the function, used by the model to decide when and
            how to call it.
        parameters:
          $ref: '#/components/schemas/FunctionParameters'
        strict:
          type: boolean
          default: false
          description: Whether to enforce strict parameter validation.
      required:
        - type
        - name
    ResponseToolChoice:
      description: >
        How the model should select which tool (or tools) to use. Either a mode
        string (`none`, `auto`, `required`) or an object forcing a specific
        tool.
      oneOf:
        - type: string
          enum:
            - none
            - auto
            - required
          description: The tool-choice mode.
        - type: object
          description: Forces the model to call a specific function tool.
          properties:
            type:
              type: string
              enum:
                - function
              x-enum-varnames:
                - ResponseToolChoiceTypeFunction
            name:
              type: string
          required:
            - type
            - name
    ResponseReasoning:
      type: object
      description: Configuration options for reasoning models.
      properties:
        effort:
          type: string
          enum:
            - minimal
            - low
            - medium
            - high
          default: medium
          nullable: true
          x-enum-varnames:
            - ResponseReasoningEffortMinimal
            - ResponseReasoningEffortLow
            - ResponseReasoningEffortMedium
            - ResponseReasoningEffortHigh
          description: >
            Constrains the effort on reasoning for reasoning models. Reducing
            effort can result in faster responses and fewer reasoning tokens.
        summary:
          type: string
          enum:
            - auto
            - concise
            - detailed
          nullable: true
          description: >
            A summary of the reasoning performed by the model, useful for
            debugging and understanding the model's reasoning process.
    ResponseTextConfig:
      type: object
      description: >
        Configuration options for a text response from the model. Can be plain
        text or structured JSON data.
      properties:
        format:
          type: object
          description: An object specifying the format that the model must output.
          properties:
            type:
              type: string
              enum:
                - text
                - json_schema
                - json_object
              x-enum-varnames:
                - ResponseTextConfigFormatTypeText
                - ResponseTextConfigFormatTypeJSONSchema
                - ResponseTextConfigFormatTypeJSONObject
              description: The type of response format being defined.
            name:
              type: string
              description: The name of the response format (used with `json_schema`).
            schema:
              $ref: '#/components/schemas/FunctionParameters'
            strict:
              type: boolean
              default: false
              description: Whether to enable strict schema adherence.
          required:
            - type
    Response:
      type: object
      description: Represents a model response returned by the Responses API.
      properties:
        id:
          type: string
          description: Unique identifier for this response.
        object:
          type: string
          description: The object type, which is always `response`.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (in seconds) of when the response was created.
        status:
          $ref: '#/components/schemas/ResponseStatus'
        model:
          type: string
          description: The model used to generate the response.
        output:
          type: array
          description: An array of content items generated by the model.
          items:
            $ref: '#/components/schemas/ResponseOutputItem'
        error:
          $ref: '#/components/schemas/ResponseError'
        incomplete_details:
          $ref: '#/components/schemas/ResponseIncompleteDetails'
        instructions:
          type: string
          nullable: true
          description: The system/developer message used to generate the response.
        max_output_tokens:
          type: integer
          nullable: true
          description: An upper bound for the number of generated tokens.
        previous_response_id:
          type: string
          nullable: true
          description: The unique ID of the previous response, if any.
        reasoning:
          $ref: '#/components/schemas/ResponseReasoning'
        temperature:
          type: number
          format: float
          nullable: true
        top_p:
          type: number
          format: float
          nullable: true
        tool_choice:
          $ref: '#/components/schemas/ResponseToolChoice'
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTool'
        text:
          $ref: '#/components/schemas/ResponseTextConfig'
        metadata:
          type: object
          additionalProperties:
            type: string
        usage:
          $ref: '#/components/schemas/ResponseUsage'
      required:
        - id
        - object
        - created_at
        - status
        - model
        - output
    ResponseStatus:
      type: string
      description: The status of the response generation.
      enum:
        - completed
        - failed
        - in_progress
        - cancelled
        - queued
        - incomplete
    ResponseError:
      type: object
      nullable: true
      description: An error object returned when the model fails to generate a response.
      properties:
        code:
          type: string
          description: The error code for the response.
        message:
          type: string
          description: A human-readable description of the error.
      required:
        - code
        - message
    ResponseIncompleteDetails:
      type: object
      nullable: true
      description: Details about why the response is incomplete.
      properties:
        reason:
          type: string
          description: The reason why the response is incomplete.
    ResponseOutputItem:
      type: object
      description: >
        An output item generated by the model: an output message, a function
        tool call, or a reasoning item.
      oneOf:
        - $ref: '#/components/schemas/ResponseOutputMessage'
        - $ref: '#/components/schemas/ResponseFunctionToolCall'
        - $ref: '#/components/schemas/ResponseReasoningItem'
    ResponseOutputMessage:
      type: object
      description: An output message from the model.
      properties:
        type:
          type: string
          enum:
            - message
          description: The type of the output item. Always `message`.
        id:
          type: string
          description: The unique ID of the output message.
        role:
          type: string
          enum:
            - assistant
          x-enum-varnames:
            - ResponseOutputMessageRoleAssistant
          description: The role of the output message. Always `assistant`.
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
          description: The status of the message.
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponseOutputContent'
      required:
        - type
        - id
        - role
        - content
    ResponseOutputContent:
      type: object
      description: A content part of an output message.
      oneOf:
        - $ref: '#/components/schemas/ResponseOutputText'
        - $ref: '#/components/schemas/ResponseOutputRefusal'
    ResponseOutputText:
      type: object
      description: A text output from the model.
      properties:
        type:
          type: string
          enum:
            - output_text
          description: The type of the output text. Always `output_text`.
        text:
          type: string
          description: The text output from the model.
      required:
        - type
        - text
    ResponseOutputRefusal:
      type: object
      description: A refusal generated by the model.
      properties:
        type:
          type: string
          enum:
            - refusal
          description: The type of the refusal. Always `refusal`.
        refusal:
          type: string
          description: The refusal explanation from the model.
      required:
        - type
        - refusal
    ResponseFunctionToolCall:
      type: object
      description: A tool call to a function generated by the model.
      properties:
        type:
          type: string
          enum:
            - function_call
          x-enum-varnames:
            - ResponseFunctionToolCallTypeFunctionCall
          description: The type of the output item. Always `function_call`.
        id:
          type: string
          description: The unique ID of the function tool call.
        call_id:
          type: string
          description: >
            The unique ID of the function tool call generated by the model,
            used to associate the call with its output.
        name:
          type: string
          description: The name of the function to run.
        arguments:
          type: string
          description: A JSON string of the arguments to pass to the function.
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
          description: The status of the function tool call.
      required:
        - type
        - call_id
        - name
        - arguments
    ResponseReasoningItem:
      type: object
      description: A reasoning item describing the model's chain of thought.
      properties:
        type:
          type: string
          enum:
            - reasoning
          description: The type of the output item. Always `reasoning`.
        id:
          type: string
          description: The unique ID of the reasoning item.
        summary:
          type: array
          description: Reasoning summary content.
          items:
            $ref: '#/components/schemas/ResponseReasoningSummaryPart'
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
          description: The status of the reasoning item.
      required:
        - type
        - id
        - summary
    ResponseReasoningSummaryPart:
      type: object
      description: A summary part of a reasoning item.
      properties:
        type:
          type: string
          enum:
            - summary_text
          description: The type of the summary. Always `summary_text`.
        text:
          type: string
          description: A summary of the reasoning output from the model.
      required:
        - type
        - text
    ResponseUsage:
      type: object
      description: Token usage details for the response.
      properties:
        input_tokens:
          type: integer
          format: int64
          default: 0
          description: The number of input tokens.
        input_tokens_details:
          type: object
          description: A detailed breakdown of the input tokens.
          properties:
            cached_tokens:
              type: integer
              format: int64
              default: 0
              description: The number of tokens retrieved from the cache.
        output_tokens:
          type: integer
          format: int64
          default: 0
          description: The number of output tokens.
        output_tokens_details:
          type: object
          description: A detailed breakdown of the output tokens.
          properties:
            reasoning_tokens:
              type: integer
              format: int64
              default: 0
              description: The number of reasoning tokens.
        total_tokens:
          type: integer
          format: int64
          default: 0
          description: The total number of tokens used (input + output).
      required:
        - input_tokens
        - output_tokens
        - total_tokens
    ResponseStreamEvent:
      type: object
      description: >
        A server-sent event emitted while streaming a response. The Responses
        API emits a sequence of typed events (for example `response.created`,
        `response.output_text.delta`, and `response.completed`). This schema
        models the common event envelope; which fields are populated depends on
        the event `type`.
      properties:
        type:
          type: string
          description: >
            The type of the streamed event, for example
            `response.output_text.delta` or `response.completed`.
        sequence_number:
          type: integer
          description: The sequence number of this event.
        response:
          $ref: '#/components/schemas/Response'
        item_id:
          type: string
          description: The ID of the output item this event relates to.
        output_index:
          type: integer
          description: The index of the output item in the response's output array.
        content_index:
          type: integer
          description: The index of the content part within the output item.
        delta:
          type: string
          description: The incremental text delta for `*.delta` events.
        text:
          type: string
          description: The finalized text for `*.done` events.
      required:
        - type
    MessagesError:
      type: object
      description: |
        An error response in the Anthropic error format.
      properties:
        type:
          type: string
          enum:
            - error
          description: Always `error`.
        error:
          type: object
          description: The error details.
          properties:
            type:
              type: string
              description: The error type (e.g. `invalid_request_error`, `api_error`).
            message:
              type: string
              description: A human-readable error message.
          required:
            - type
            - message
      required:
        - type
        - error
    CacheControl:
      type: object
      description: |
        Cache control settings for prompt caching. Currently only
        `ephemeral` caching is supported.
      properties:
        type:
          type: string
          enum:
            - ephemeral
          description: The cache control type. Currently only `ephemeral`.
      required:
        - type
    MessagesTextBlock:
      type: object
      description: A text content block in a Messages API request or response.
      properties:
        type:
          type: string
          enum:
            - text
          description: Content type identifier. Always `text`.
        text:
          type: string
          description: The text content.
        cache_control:
          $ref: '#/components/schemas/CacheControl'
      required:
        - type
        - text
    MessagesImageSource:
      type: object
      description: |
        The source of an image content block. Can be a base64-encoded
        image or a URL.
      properties:
        type:
          type: string
          enum:
            - base64
            - url
          description: The source type.
        media_type:
          type: string
          description: |
            The media type of the image (e.g. `image/jpeg`, `image/png`,
            `image/gif`, `image/webp`). Required when `type` is `base64`.
        data:
          type: string
          description: |
            Base64-encoded image data. Required when `type` is `base64`.
        url:
          type: string
          description: |
            URL of the image. Required when `type` is `url`.
      required:
        - type
    MessagesImageBlock:
      type: object
      description: An image content block in a Messages API request.
      properties:
        type:
          type: string
          enum:
            - image
          description: Content type identifier. Always `image`.
        source:
          $ref: '#/components/schemas/MessagesImageSource'
        cache_control:
          $ref: '#/components/schemas/CacheControl'
      required:
        - type
        - source
    MessagesDocumentSource:
      type: object
      description: |
        The source of a document content block. Can be a base64-encoded
        document or a URL.
      properties:
        type:
          type: string
          enum:
            - base64
            - url
          description: The source type.
        media_type:
          type: string
          description: |
            The media type of the document (e.g. `application/pdf`).
            Required when `type` is `base64`.
        data:
          type: string
          description: |
            Base64-encoded document data. Required when `type` is `base64`.
        url:
          type: string
          description: |
            URL of the document. Required when `type` is `url`.
      required:
        - type
    MessagesDocumentBlock:
      type: object
      description: A document content block in a Messages API request.
      properties:
        type:
          type: string
          enum:
            - document
          description: Content type identifier. Always `document`.
        source:
          $ref: '#/components/schemas/MessagesDocumentSource'
        cache_control:
          $ref: '#/components/schemas/CacheControl'
      required:
        - type
        - source
    MessagesToolUseBlock:
      type: object
      description: A tool use content block in a Messages API request or response.
      properties:
        type:
          type: string
          enum:
            - tool_use
          description: Content type identifier. Always `tool_use`.
        id:
          type: string
          description: The unique identifier for this tool use block.
        name:
          type: string
          description: The name of the tool being called.
        input:
          type: object
          description: The input parameters for the tool.
          additionalProperties: true
      required:
        - type
        - id
        - name
        - input
    MessagesToolResultBlock:
      type: object
      description: A tool result content block in a Messages API request.
      properties:
        type:
          type: string
          enum:
            - tool_result
          description: Content type identifier. Always `tool_result`.
        tool_use_id:
          type: string
          description: The ID of the tool use this result is for.
        content:
          description: |
            The result content. Can be a string or an array of content blocks.
          oneOf:
            - type: string
              description: Text result content.
            - type: array
              items:
                $ref: '#/components/schemas/MessagesTextBlock'
        is_error:
          type: boolean
          description: Whether the tool execution resulted in an error.
        cache_control:
          $ref: '#/components/schemas/CacheControl'
      required:
        - type
        - tool_use_id
    MessagesThinkingBlock:
      type: object
      description: A thinking content block in a Messages API request or response.
      properties:
        type:
          type: string
          enum:
            - thinking
          description: Content type identifier. Always `thinking`.
        thinking:
          type: string
          description: The thinking content.
        signature:
          type: string
          description: |
            The signature for verifying the thinking content. Must be
            passed back when continuing a conversation with extended thinking.
      required:
        - type
        - thinking
        - signature
    MessagesRedactedThinkingBlock:
      type: object
      description: |
        A redacted thinking content block in a Messages API request or
        response. Emitted when thinking content is encrypted for safety
        reasons; must be passed back unchanged in multi-turn conversations.
      properties:
        type:
          type: string
          enum:
            - redacted_thinking
          description: Content type identifier. Always `redacted_thinking`.
        data:
          type: string
          description: The encrypted thinking content.
      required:
        - type
        - data
    MessagesRequestContentBlock:
      type: object
      description: A content block within a Messages API request message.
      oneOf:
        - $ref: '#/components/schemas/MessagesTextBlock'
        - $ref: '#/components/schemas/MessagesImageBlock'
        - $ref: '#/components/schemas/MessagesToolUseBlock'
        - $ref: '#/components/schemas/MessagesToolResultBlock'
        - $ref: '#/components/schemas/MessagesDocumentBlock'
        - $ref: '#/components/schemas/MessagesThinkingBlock'
        - $ref: '#/components/schemas/MessagesRedactedThinkingBlock'
    MessagesMessage:
      type: object
      description: A message in a Messages API request.
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
          x-enum-varnames:
            - MessagesMessageRoleUser
            - MessagesMessageRoleAssistant
          description: The role of the message sender.
        content:
          description: |
            The content of the message. Can be a string or an array of
            content blocks.
          oneOf:
            - type: string
              description: Text content.
            - type: array
              items:
                $ref: '#/components/schemas/MessagesRequestContentBlock'
      required:
        - role
        - content
    MessagesTool:
      type: object
      description: |
        A tool definition in the Messages API format. Uses the same
        function tool shape as the Responses API but with an optional
        `cache_control` field for prompt caching.
      properties:
        name:
          type: string
          description: The name of the tool.
        description:
          type: string
          description: A description of what the tool does.
        input_schema:
          $ref: '#/components/schemas/FunctionParameters'
        cache_control:
          $ref: '#/components/schemas/CacheControl'
      required:
        - name
        - input_schema
    MessagesToolChoice:
      description: |
        Controls which (if any) tool is called by the model. `auto` means
        the model can decide, `any` means the model must use a tool, and
        `tool` forces a specific tool.
      oneOf:
        - type: string
          enum:
            - auto
            - any
          description: The tool choice mode.
        - type: object
          description: Forces the model to use a specific tool.
          properties:
            type:
              type: string
              enum:
                - tool
              x-enum-varnames:
                - MessagesToolChoiceTypeTool
              description: Always `tool`.
            name:
              type: string
              description: The name of the tool to use.
          required:
            - type
            - name
    MessagesMetadata:
      type: object
      description: Metadata for a Messages API request.
      properties:
        user_id:
          type: string
          description: An external identifier for the user.
    CreateMessagesRequest:
      type: object
      description: |
        Request body for creating a message via the Anthropic-compatible
        Messages API.
      properties:
        model:
          type: string
          description: The model to use for generating the message.
        max_tokens:
          type: integer
          description: |
            The maximum number of tokens to generate before stopping.
        system:
          description: |
            The system prompt. Can be a string or an array of system content
            blocks (for prompt caching).
          oneOf:
            - type: string
              description: System prompt as a string.
            - type: array
              items:
                $ref: '#/components/schemas/MessagesTextBlock'
        messages:
          type: array
          description: |
            The messages to generate a response for. Each message has a
            `role` (user or assistant) and `content`.
          items:
            $ref: '#/components/schemas/MessagesMessage'
        tools:
          type: array
          description: |
            Definitions of tools the model may call. Each tool can include
            `cache_control` for prompt caching.
          items:
            $ref: '#/components/schemas/MessagesTool'
        tool_choice:
          $ref: '#/components/schemas/MessagesToolChoice'
        stream:
          type: boolean
          default: false
          description: |
            Whether to stream the response using server-sent events.
        temperature:
          type: number
          format: float
          description: |
            Amount of randomness injected into the response. Ranges from
            0.0 to 1.0. Use closer to 0 for analytical / multiple choice,
            closer to 1 for creative and generative tasks.
        top_p:
          type: number
          format: float
          description: |
            Use nucleus sampling. Only consider the tokens with top_p
            probability mass.
        top_k:
          type: integer
          description: |
            Only sample from the top K options for each subsequent token.
        stop_sequences:
          type: array
          description: |
            Custom text sequences that will cause the model to stop
            generating.
          items:
            type: string
        metadata:
          $ref: '#/components/schemas/MessagesMetadata'
        thinking:
          type: object
          description: |
            Configuration for extended thinking.
          properties:
            type:
              type: string
              enum:
                - enabled
              description: Always `enabled`.
            budget_tokens:
              type: integer
              description: |
                The maximum number of tokens the model is allowed to use
                for thinking.
          required:
            - type
            - budget_tokens
        output_config:
          $ref: '#/components/schemas/MessagesOutputConfig'
      required:
        - model
        - max_tokens
        - messages
    MessagesOutputConfig:
      type: object
      description: |
        Output configuration for a Messages API request.
      properties:
        effort:
          type: string
          enum:
            - low
            - medium
            - high
            - xhigh
            - max
          x-enum-varnames:
            - MessagesOutputConfigEffortLow
            - MessagesOutputConfigEffortMedium
            - MessagesOutputConfigEffortHigh
            - MessagesOutputConfigEffortXhigh
            - MessagesOutputConfigEffortMax
          description: |
            Constrains how much effort the model spends on reasoning.
            Lower effort yields faster responses and fewer reasoning
            tokens.
    MessagesResponseContentBlock:
      type: object
      description: A content block within a Messages API response.
      oneOf:
        - $ref: '#/components/schemas/MessagesTextBlock'
        - $ref: '#/components/schemas/MessagesToolUseBlock'
        - $ref: '#/components/schemas/MessagesThinkingBlock'
        - $ref: '#/components/schemas/MessagesRedactedThinkingBlock'
    MessagesUsage:
      type: object
      description: |
        Token usage statistics for a Messages API response, including
        cache metrics.
      properties:
        input_tokens:
          type: integer
          format: int64
          default: 0
          description: The number of input tokens.
        output_tokens:
          type: integer
          format: int64
          default: 0
          description: The number of output tokens.
        cache_creation_input_tokens:
          type: integer
          format: int64
          default: 0
          description: |
            The number of tokens used for cache creation.
        cache_read_input_tokens:
          type: integer
          format: int64
          default: 0
          description: |
            The number of tokens read from the cache.
      required:
        - input_tokens
        - output_tokens
    MessagesResponse:
      type: object
      description: |
        A message response from the Anthropic-compatible Messages API.
      properties:
        id:
          type: string
          description: Unique identifier for this message.
        type:
          type: string
          enum:
            - message
          description: Always `message`.
        role:
          type: string
          enum:
            - assistant
          x-enum-varnames:
            - MessagesResponseRoleAssistant
          description: Always `assistant`.
        content:
          type: array
          description: The content blocks generated by the model.
          items:
            $ref: '#/components/schemas/MessagesResponseContentBlock'
        model:
          type: string
          description: The model used to generate the message.
        stop_reason:
          type: string
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
            - pause_turn
            - refusal
          description: |
            The reason the model stopped generating.
        stop_sequence:
          type: string
          nullable: true
          description: |
            The stop sequence that caused the model to stop, if any.
        usage:
          $ref: '#/components/schemas/MessagesUsage'
      required:
        - id
        - type
        - role
        - content
        - model
        - stop_reason
        - usage
    MessagesStreamEvent:
      type: object
      description: |
        A server-sent event emitted while streaming a Messages API response.
        The Anthropic Messages API emits a sequence of typed events
        (`message_start`, `content_block_start`, `content_block_delta`,
        `content_block_stop`, `message_delta`, `message_stop`, `ping`).
      properties:
        type:
          type: string
          enum:
            - message_start
            - content_block_start
            - content_block_delta
            - content_block_stop
            - message_delta
            - message_stop
            - ping
            - error
          description: The type of the streamed event.
        message:
          $ref: '#/components/schemas/MessagesResponse'
          description: |
            Present in `message_start` events. Contains the initial message.
        index:
          type: integer
          description: |
            Present in `content_block_*` events. The index of the content
            block.
        content_block:
          $ref: '#/components/schemas/MessagesResponseContentBlock'
          description: |
            Present in `content_block_start` events. Contains the content
            block.
        delta:
          type: object
          description: |
            Present in `content_block_delta` and `message_delta` events.
            Contains the incremental update.
          properties:
            type:
              type: string
              description: |
                The type of delta. For text deltas this is `text_delta`,
                for streamed tool inputs this is `input_json_delta`, for
                thinking deltas this is `thinking_delta`, for thinking
                signatures this is `signature_delta`.
            text:
              type: string
              description: The incremental text (for `text_delta`).
            partial_json:
              type: string
              description: |
                The incremental JSON string of the tool input
                (for `input_json_delta`).
            thinking:
              type: string
              description: The incremental thinking content (for `thinking_delta`).
            signature:
              type: string
              description: The thinking signature (for `signature_delta`).
            stop_reason:
              type: string
              description: The stop reason (for `message_delta`).
            stop_sequence:
              type: string
              nullable: true
              description: The stop sequence (for `message_delta`).
        usage:
          $ref: '#/components/schemas/MessagesUsage'
          description: |
            Present in `message_delta` events as a sibling of `delta`.
            Contains cumulative usage for the message.
        error:
          $ref: '#/components/schemas/MessagesError'
          description: |
            Present in `error` events. Contains the error details.
      required:
        - type
    Config:
      x-config:
        sections:
          - general:
              title: 'General settings'
              settings:
                - name: environment
                  env: 'ENVIRONMENT'
                  type: string
                  default: 'production'
                  description: 'The environment'
                - name: allowed_models
                  env: 'ALLOWED_MODELS'
                  type: string
                  default: ''
                  description: 'Comma-separated list of models to allow. If empty, all models will be available'
                - name: disallowed_models
                  env: 'DISALLOWED_MODELS'
                  type: string
                  default: ''
                  description: 'Comma-separated list of models to disallow. If empty, no models will be blocked. Takes lower precedence than ALLOWED_MODELS'
                - name: vision_enabled
                  env: 'VISION_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable vision/multimodal handling for all providers. When enabled, image content is stripped from requests to models known to accept only non-image input; unknown models are passed through. When disabled, image content is forwarded to the provider untouched'
                - name: images_enabled
                  env: 'IMAGES_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable the Images API (POST /v1/images/generations, /v1/images/edits). When disabled, the endpoints return a 404. Only providers with images support (currently openai) can serve these endpoints'
                - name: audio_enabled
                  env: 'AUDIO_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable the Audio API (POST /v1/audio/speech, POST /v1/audio/sfx, POST /v1/audio/music). When disabled, the endpoints return a 404. Served by providers with speech, sound-effect or music support (currently openai and elevenlabs) or by the local llama-tts engine'
                - name: videos_enabled
                  env: 'VIDEOS_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable the Videos API (POST /v1/videos, GET /v1/videos/{video_id}, GET /v1/videos/{video_id}/content). When disabled, the endpoints return a 404. Only providers with video support (currently elevenlabs) can serve these endpoints'
                - name: audio_local_auto_download
                  env: 'AUDIO_LOCAL_AUTO_DOWNLOAD'
                  type: bool
                  default: 'true'
                  description: 'Allow downloading the llama-tts binary and GGUF models, in the background at startup when the Audio API is enabled. The pinned GGUF models are treated as done once present in the cache, whoever wrote them (an earlier run, the CLI, a mounted volume, a pre-baked image layer), while a cached binary whose sha256 differs from the latest release is replaced. A llama-tts found on PATH is left alone - upgrading it is the operator''s job. When false, the gateway serves only from the existing cache or PATH and returns an actionable error when assets are missing'
                - name: audio_local_max_concurrency
                  env: 'AUDIO_LOCAL_MAX_CONCURRENCY'
                  type: int
                  default: '2'
                  description: 'Maximum concurrent local speech syntheses; requests beyond the limit queue'
                - name: audio_local_timeout
                  env: 'AUDIO_LOCAL_TIMEOUT'
                  type: int
                  default: '300'
                  description: 'Timeout in seconds for a single local speech synthesis'
                - name: debug_content_truncate_words
                  env: 'DEBUG_CONTENT_TRUNCATE_WORDS'
                  type: int
                  default: '10'
                  description: 'Number of words to truncate per content section in debug logs (development mode only)'
                - name: debug_max_messages
                  env: 'DEBUG_MAX_MESSAGES'
                  type: int
                  default: '100'
                  description: 'Maximum number of messages to show in debug logs (development mode only)'
          - telemetry:
              title: 'Telemetry'
              settings:
                - name: telemetry_enabled
                  env: 'TELEMETRY_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable telemetry'
                - name: telemetry_metrics_push_enabled
                  env: 'TELEMETRY_METRICS_PUSH_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable the OTLP metrics push endpoint (POST /v1/metrics)'
                - name: telemetry_metrics_port
                  env: 'TELEMETRY_METRICS_PORT'
                  type: string
                  default: '9464'
                  description: 'Port for telemetry metrics server'
                - name: telemetry_tracing_enabled
                  env: 'TELEMETRY_TRACING_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable OpenTelemetry tracing spans (requires TELEMETRY_ENABLED)'
                - name: telemetry_tracing_otlp_endpoint
                  env: 'TELEMETRY_TRACING_OTLP_ENDPOINT'
                  type: string
                  default: 'http://localhost:4318'
                  description: 'OTLP HTTP endpoint for trace export'
          - mcp:
              title: 'Model Context Protocol (MCP)'
              settings:
                - name: mcp_enabled
                  env: 'MCP_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable MCP'
                - name: mcp_expose
                  env: 'MCP_EXPOSE'
                  type: bool
                  default: 'false'
                  description: 'Expose the gateway as an MCP server on POST /mcp (requires MCP_ENABLED)'
                - name: mcp_resource_url
                  env: 'MCP_RESOURCE_URL'
                  type: string
                  description: 'Canonical public URL of POST /mcp, e.g. https://gateway.example.com/mcp. Published as the resource of the OAuth 2.0 Protected Resource Metadata (RFC 9728) document served at /.well-known/oauth-protected-resource/mcp, and pointed at by the resource_metadata of every 401 challenge on /mcp. Defaults to the request scheme (honouring X-Forwarded-Proto) and Host with /mcp appended; set it behind an ingress that rewrites either'
                - name: mcp_servers
                  env: 'MCP_SERVERS'
                  type: string
                  description: 'Comma-separated list of MCP servers as alias=url, e.g. deepwiki=https://mcp.deepwiki.com/mcp,http://mcp-time-server:8081/mcp. Without alias= the alias is derived from the URL host. Aliases must match ^[a-z0-9_-]+$, be unique, must not be the reserved alias tools, and namespace the tools as mcp_<alias>_<tool>'
                - name: mcp_tool_mode
                  env: 'MCP_TOOL_MODE'
                  type: string
                  default: 'selector'
                  description: 'How MCP tools are exposed to the model. selector injects two meta-tools for discovery and dispatch; direct injects every tool schema'
                - name: mcp_include_tools
                  env: 'MCP_INCLUDE_TOOLS'
                  type: string
                  description: 'Comma-separated list of MCP tool names to inject, matched against either the bare tool name or the namespaced <alias>_<tool name> form. If empty, all tools are injected. Takes precedence over MCP_EXCLUDE_TOOLS'
                - name: mcp_exclude_tools
                  env: 'MCP_EXCLUDE_TOOLS'
                  type: string
                  description: 'Comma-separated list of MCP tool names to skip injecting, matched against either the bare tool name or the namespaced <alias>_<tool name> form. If empty, no tools are excluded. Takes lower precedence than MCP_INCLUDE_TOOLS'
                - name: mcp_client_timeout
                  env: 'MCP_CLIENT_TIMEOUT'
                  type: time.Duration
                  default: '5s'
                  description: 'MCP client HTTP timeout'
                - name: mcp_dial_timeout
                  env: 'MCP_DIAL_TIMEOUT'
                  type: time.Duration
                  default: '3s'
                  description: 'MCP client dial timeout'
                - name: mcp_tls_handshake_timeout
                  env: 'MCP_TLS_HANDSHAKE_TIMEOUT'
                  type: time.Duration
                  default: '3s'
                  description: 'MCP client TLS handshake timeout'
                - name: mcp_response_header_timeout
                  env: 'MCP_RESPONSE_HEADER_TIMEOUT'
                  type: time.Duration
                  default: '3s'
                  description: 'MCP client response header timeout'
                - name: mcp_expect_continue_timeout
                  env: 'MCP_EXPECT_CONTINUE_TIMEOUT'
                  type: time.Duration
                  default: '1s'
                  description: 'MCP client expect continue timeout'
                - name: mcp_request_timeout
                  env: 'MCP_REQUEST_TIMEOUT'
                  type: time.Duration
                  default: '5s'
                  description: 'Timeout for one MCP discovery request: the startup server discovery and each tools/list refresh. Tool calls are bounded by MCP_CLIENT_TIMEOUT instead'
                - name: mcp_max_retries
                  env: 'MCP_MAX_RETRIES'
                  type: int
                  default: '3'
                  description: 'Maximum number of connection retry attempts'
                - name: mcp_retry_interval
                  env: 'MCP_RETRY_INTERVAL'
                  type: time.Duration
                  default: '5s'
                  description: 'Interval between connection retry attempts'
                - name: mcp_initial_backoff
                  env: 'MCP_INITIAL_BACKOFF'
                  type: time.Duration
                  default: '1s'
                  description: 'Initial backoff duration for exponential backoff retry'
                - name: mcp_enable_reconnect
                  env: 'MCP_ENABLE_RECONNECT'
                  type: bool
                  default: 'true'
                  description: 'Enable automatic reconnection for failed servers'
                - name: mcp_reconnect_interval
                  env: 'MCP_RECONNECT_INTERVAL'
                  type: time.Duration
                  default: '30s'
                  description: 'Interval between reconnection attempts'
                - name: mcp_polling_enabled
                  env: 'MCP_POLLING_ENABLED'
                  type: bool
                  default: 'true'
                  description: 'Enable health check polling'
                - name: mcp_polling_interval
                  env: 'MCP_POLLING_INTERVAL'
                  type: time.Duration
                  default: '30s'
                  description: 'Interval between health check polling requests'
                - name: mcp_polling_timeout
                  env: 'MCP_POLLING_TIMEOUT'
                  type: time.Duration
                  default: '5s'
                  description: 'Timeout for individual health check requests'
                - name: mcp_disable_healthcheck_logs
                  env: 'MCP_DISABLE_HEALTHCHECK_LOGS'
                  type: bool
                  default: 'true'
                  description: 'Disable health check log messages to reduce noise'
          - a2a:
              title: 'Agent-to-Agent (A2A)'
              settings:
                - name: a2a_enabled
                  env: 'A2A_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Expose the gateway as an A2A server that delegates every call to the agents in A2A_AGENTS: GET /.well-known/agent-card.json, POST /a2a and GET /a2a/agents. When disabled the routes return 404 and nothing A2A-related runs'
                - name: a2a_agents
                  env: 'A2A_AGENTS'
                  type: string
                  description: 'Comma-separated list of A2A agents as alias=url, e.g. research=http://research-agent:8080,http://mock-agent:8080. Without alias= the alias is derived from the URL host. Aliases must match ^[a-z0-9_-]+$ and be unique; they prefix the skill ids on the gateway card, name the tenant of the per-agent interface, and prefix every task id the gateway hands out as <alias>:<task id>. Per-agent credentials go in the url as basic auth'
                - name: a2a_resource_url
                  env: 'A2A_RESOURCE_URL'
                  type: string
                  description: 'Canonical public URL of POST /a2a, e.g. https://gateway.example.com/a2a. Published as the url of the gateway agent card interfaces and as the resource of the OAuth 2.0 Protected Resource Metadata (RFC 9728) document served at /.well-known/oauth-protected-resource/a2a. Defaults to the request scheme (honouring X-Forwarded-Proto) and Host with /a2a appended; set it behind an ingress that rewrites either'
                - name: a2a_client_timeout
                  env: 'A2A_CLIENT_TIMEOUT'
                  type: time.Duration
                  default: '30s'
                  description: 'Timeout for one non-streaming call to an agent, including the agent card fetch'
                - name: a2a_stream_idle_timeout
                  env: 'A2A_STREAM_IDLE_TIMEOUT'
                  type: time.Duration
                  default: '5m'
                  description: 'Idle cutoff for a relayed SendStreamingMessage or SubscribeToTask stream: the relay closes when the agent sends nothing for this long. 0 disables the cutoff'
                - name: a2a_card_refresh_interval
                  env: 'A2A_CARD_REFRESH_INTERVAL'
                  type: time.Duration
                  default: '5m'
                  description: 'Interval at which agent cards are re-fetched in the background so unreachable agents are retried and skill changes picked up. Cards are always fetched once at startup; 0 disables the background refresh'
          - auth:
              title: 'Authentication'
              settings:
                - name: auth_enabled
                  env: 'AUTH_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable authentication'
                - name: auth_oidc_issuer
                  env: 'AUTH_OIDC_ISSUER'
                  type: string
                  description: 'OIDC issuer URL. Discovery runs once at startup against {issuer}/.well-known/openid-configuration'
                - name: auth_oidc_client_id
                  env: 'AUTH_OIDC_CLIENT_ID'
                  type: string
                  description: 'OIDC client ID. Used as the expected token audience when AUTH_OIDC_AUDIENCE is empty'
                - name: auth_oidc_audience
                  env: 'AUTH_OIDC_AUDIENCE'
                  type: string
                  description: 'Comma-separated list of accepted aud values, for example an API identifier. Defaults to AUTH_OIDC_CLIENT_ID'
          - guardrails:
              title: 'Guardrails'
              settings:
                - name: guardrails_enabled
                  env: 'GUARDRAILS_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable gateway guardrails (OPA/Rego policy enforcement)'
                - name: guardrails_policy_dir
                  env: 'GUARDRAILS_POLICY_DIR'
                  type: string
                  description: 'Directory of .rego files compiled at startup'
                - name: guardrails_fail_mode
                  env: 'GUARDRAILS_FAIL_MODE'
                  type: string
                  default: 'closed'
                  description: 'closed or open: behavior on policy/external error or timeout'
                - name: guardrails_external_url
                  env: 'GUARDRAILS_EXTERNAL_URL'
                  type: string
                  description: 'Optional external HTTP guardrail service'
                - name: guardrails_external_timeout
                  env: 'GUARDRAILS_EXTERNAL_TIMEOUT'
                  type: time.Duration
                  default: '5s'
                  description: 'Timeout for the external guardrail service'
          - server:
              title: 'Server settings'
              settings:
                - name: host
                  env: 'SERVER_HOST'
                  type: string
                  default: '127.0.0.1'
                  description: 'Server host'
                - name: port
                  env: 'SERVER_PORT'
                  type: string
                  default: '8080'
                  description: 'Server port'
                - name: read_timeout
                  env: 'SERVER_READ_TIMEOUT'
                  type: time.Duration
                  default: '30s'
                  description: 'Read timeout'
                - name: write_timeout
                  env: 'SERVER_WRITE_TIMEOUT'
                  type: time.Duration
                  default: '30s'
                  description: 'Write timeout'
                - name: idle_timeout
                  env: 'SERVER_IDLE_TIMEOUT'
                  type: time.Duration
                  default: '120s'
                  description: 'Idle timeout'
                - name: max_request_body_size
                  env: 'SERVER_MAX_REQUEST_BODY_SIZE'
                  type: int
                  default: '10485760'
                  description: 'Maximum request body size in bytes (10 MiB)'
                - name: tls_cert_path
                  env: 'SERVER_TLS_CERT_PATH'
                  type: string
                  description: 'TLS certificate path'
                - name: tls_key_path
                  env: 'SERVER_TLS_KEY_PATH'
                  type: string
                  description: 'TLS key path'
          - client:
              title: 'Client settings'
              settings:
                - name: max_idle_conns
                  env: 'CLIENT_MAX_IDLE_CONNS'
                  type: int
                  default: '20'
                  description: 'Maximum idle connections'
                - name: max_idle_conns_per_host
                  env: 'CLIENT_MAX_IDLE_CONNS_PER_HOST'
                  type: int
                  default: '20'
                  description: 'Maximum idle connections per host'
                - name: idle_conn_timeout
                  env: 'CLIENT_IDLE_CONN_TIMEOUT'
                  type: time.Duration
                  default: '30s'
                  description: 'Idle connection timeout'
                - name: tls_min_version
                  env: 'CLIENT_TLS_MIN_VERSION'
                  type: string
                  default: 'TLS12'
                  description: 'Minimum TLS version'
                - name: disable_compression
                  env: 'CLIENT_DISABLE_COMPRESSION'
                  type: bool
                  default: 'true'
                  description: 'Disable compression for faster streaming'
                - name: response_header_timeout
                  env: 'CLIENT_RESPONSE_HEADER_TIMEOUT'
                  type: time.Duration
                  default: '10s'
                  description: 'Response header timeout'
                - name: expect_continue_timeout
                  env: 'CLIENT_EXPECT_CONTINUE_TIMEOUT'
                  type: time.Duration
                  default: '1s'
                  description: 'Expect continue timeout'
          - providers:
              title: 'Providers'
              settings:
                - name: anthropic_api_url
                  env: 'ANTHROPIC_API_URL'
                  type: string
                  default: 'https://api.anthropic.com/v1'
                  description: 'Anthropic API URL'
                - name: anthropic_api_key
                  env: 'ANTHROPIC_API_KEY'
                  type: string
                  description: 'Anthropic API Key'
                  secret: true
                - name: cloudflare_api_url
                  env: 'CLOUDFLARE_API_URL'
                  type: string
                  default: 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai'
                  description: 'Cloudflare API URL'
                - name: cloudflare_api_key
                  env: 'CLOUDFLARE_API_KEY'
                  type: string
                  description: 'Cloudflare API Key'
                  secret: true
                - name: cohere_api_url
                  env: 'COHERE_API_URL'
                  type: string
                  default: 'https://api.cohere.ai'
                  description: 'Cohere API URL'
                - name: cohere_api_key
                  env: 'COHERE_API_KEY'
                  type: string
                  description: 'Cohere API Key'
                  secret: true
                - name: groq_api_url
                  env: 'GROQ_API_URL'
                  type: string
                  default: 'https://api.groq.com/openai/v1'
                  description: 'Groq API URL'
                - name: groq_api_key
                  env: 'GROQ_API_KEY'
                  type: string
                  description: 'Groq API Key'
                  secret: true
                - name: llamacpp_api_url
                  env: 'LLAMACPP_API_URL'
                  type: string
                  default: 'http://llamacpp:8080/v1'
                  description: 'llama.cpp API URL'
                - name: llamacpp_api_key
                  env: 'LLAMACPP_API_KEY'
                  type: string
                  description: 'llama.cpp API Key'
                  secret: true
                - name: ollama_api_url
                  env: 'OLLAMA_API_URL'
                  type: string
                  default: 'http://ollama:8080/v1'
                  description: 'Ollama API URL'
                - name: ollama_api_key
                  env: 'OLLAMA_API_KEY'
                  type: string
                  description: 'Ollama API Key'
                  secret: true
                - name: ollama_cloud_api_url
                  env: 'OLLAMA_CLOUD_API_URL'
                  type: string
                  default: 'https://ollama.com/v1'
                  description: 'Ollama Cloud API URL'
                - name: ollama_cloud_api_key
                  env: 'OLLAMA_CLOUD_API_KEY'
                  type: string
                  description: 'Ollama Cloud API Key'
                  secret: true
                - name: openai_api_url
                  env: 'OPENAI_API_URL'
                  type: string
                  default: 'https://api.openai.com/v1'
                  description: 'OpenAI API URL'
                - name: openai_api_key
                  env: 'OPENAI_API_KEY'
                  type: string
                  description: 'OpenAI API Key'
                  secret: true
                - name: deepseek_api_url
                  env: 'DEEPSEEK_API_URL'
                  type: string
                  default: 'https://api.deepseek.com'
                  description: 'DeepSeek API URL'
                - name: deepseek_api_key
                  env: 'DEEPSEEK_API_KEY'
                  type: string
                  description: 'DeepSeek API Key'
                  secret: true
                - name: elevenlabs_api_url
                  env: 'ELEVENLABS_API_URL'
                  type: string
                  default: 'https://api.elevenlabs.io/v1'
                  description: 'ElevenLabs API URL'
                - name: elevenlabs_api_key
                  env: 'ELEVENLABS_API_KEY'
                  type: string
                  description: 'ElevenLabs API Key'
                  secret: true
                - name: google_api_url
                  env: 'GOOGLE_API_URL'
                  type: string
                  default: 'https://generativelanguage.googleapis.com/v1beta/openai'
                  description: 'Google API URL'
                - name: google_api_key
                  env: 'GOOGLE_API_KEY'
                  type: string
                  description: 'Google API Key'
                  secret: true
                - name: mistral_api_url
                  env: 'MISTRAL_API_URL'
                  type: string
                  default: 'https://api.mistral.ai/v1'
                  description: 'Mistral API URL'
                - name: mistral_api_key
                  env: 'MISTRAL_API_KEY'
                  type: string
                  description: 'Mistral API Key'
                  secret: true
                - name: minimax_api_url
                  env: 'MINIMAX_API_URL'
                  type: string
                  default: 'https://api.minimax.io/v1'
                  description: 'MiniMax API URL'
                - name: minimax_api_key
                  env: 'MINIMAX_API_KEY'
                  type: string
                  description: 'MiniMax API Key'
                  secret: true
                - name: moonshot_api_url
                  env: 'MOONSHOT_API_URL'
                  type: string
                  default: 'https://api.moonshot.ai/v1'
                  description: 'Moonshot API URL'
                - name: moonshot_api_key
                  env: 'MOONSHOT_API_KEY'
                  type: string
                  description: 'Moonshot API Key'
                  secret: true
                - name: nvidia_api_url
                  env: 'NVIDIA_API_URL'
                  type: string
                  default: 'https://integrate.api.nvidia.com/v1'
                  description: 'NVIDIA API URL'
                - name: nvidia_api_key
                  env: 'NVIDIA_API_KEY'
                  type: string
                  description: 'NVIDIA API Key'
                  secret: true
                - name: zai_api_url
                  env: 'ZAI_API_URL'
                  type: string
                  default: 'https://api.z.ai/api/coding/paas/v4'
                  description: 'ZAI API URL - the default is the GLM Coding Plan endpoint, so subscription requests draw on the plan. Users without a Coding Plan must set https://api.z.ai/api/paas/v4 to be billed pay-as-you-go'
                - name: zai_api_key
                  env: 'ZAI_API_KEY'
                  type: string
                  description: 'ZAI API Key'
                  secret: true
          - routing:
              title: 'Routing'
              settings:
                - name: routing_enabled
                  env: 'ROUTING_ENABLED'
                  type: bool
                  default: 'false'
                  description: 'Enable gateway-native model routing: logical model aliases backed by a pool of upstream provider deployments, selected round-robin per replica. Opt-in; when disabled, direct provider/model routing is unchanged'
                - name: routing_config_path
                  env: 'ROUTING_CONFIG_PATH'
                  type: string
                  default: ''
                  description: 'Path to a YAML file mapping logical model aliases to their upstream deployment pools. Required when ROUTING_ENABLED is true'