---
openapi: "3.0.3"
info:
  title: Consumption API
  description: |
    # Overview: Consumption API
    
    The Consumption API provides OpenAI-compatible endpoints for consuming LLM inference on The Grid. It follows the standard chat completions API format, making it easy to integrate with existing applications.
    
    ## Base URL
    
    | Type | Base URL |
    |------|----------|
    | **HTTP** | `https://api.cortex.thegrid.ai/api/v1` |
    
    ## Authentication
    
    The Consumption API uses **Bearer Token** authentication. Include your API key in the `Authorization` header of every request.
    
    | Header | Description |
    |--------|-------------|
    | `Authorization` | Bearer token in format: `Bearer YOUR_API_KEY` |
    
    **Example Request Header:**
    ```http
    Authorization: Bearer sk_live_abc123...
    Content-Type: application/json
    ```
    
    {% hint style="info" %}
    You can generate API keys from your [Grid Dashboard](https://thegrid.ai/dashboard). Keep your API keys secure and never expose them in client-side code.
    {% endhint %}
    
    ## Request Format
    
    - **Content-Type**: `application/json` for all POST requests
    - **Body**: JSON-encoded request body
    
    ## Response Format
    
    **Success Response:**
    ```json
    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1677858242,
      "model": "chat-prime",
      "choices": [...]
    }
    ```
    
    **Error Response:**
    ```json
    {
      "errors": {
        "detail": "Error message describing the issue"
      }
    }
    ```
    
    ## Streaming Responses
    
    For real-time token generation, set `stream: true` in your request. The response will be delivered as Server-Sent Events (SSE).
    
    **Request:**
    ```json
    {
      "model": "chat-prime",
      "messages": [{"role": "user", "content": "Hello!"}],
      "stream": true
    }
    ```
    
    **Response Format:**
    
    Each SSE event contains a `data:` field with a JSON chunk:
    
    ```
    data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1677858242,"model":"chat-prime","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
    
    data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1677858242,"model":"chat-prime","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
    
    data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1677858242,"model":"chat-prime","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
    
    data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1677858242,"model":"chat-prime","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
    
    data: [DONE]
    ```
    
    {% hint style="info" %}
    **Parsing tips:**
    - Each chunk is prefixed with `data: `
    - The stream ends with `data: [DONE]`
    - Collect `delta.content` from each chunk to build the full response
    - Check `finish_reason` to detect completion (`stop`, `length`, `tool_calls`)
    {% endhint %}
    
    {% tabs %}
    {% tab title="Python" %}
    ```python
    import requests
    
    response = requests.post(
        'https://api.cortex.thegrid.ai/api/v1/chat/completions',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'model': 'chat-prime',
            'messages': [{'role': 'user', 'content': 'Hello!'}],
            'stream': True
        },
        stream=True
    )
    
    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: ') and line != 'data: [DONE]':
                import json
                chunk = json.loads(line[6:])
                content = chunk['choices'][0]['delta'].get('content', '')
                print(content, end='', flush=True)
    ```
    {% endtab %}
    
    {% tab title="JavaScript" %}
    ```javascript
    const response = await fetch('https://api.cortex.thegrid.ai/api/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'chat-prime',
        messages: [{ role: 'user', content: 'Hello!' }],
        stream: true
      })
    });
    
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      
      const chunk = decoder.decode(value);
      const lines = chunk.split('\n').filter(line => line.startsWith('data: '));
      
      for (const line of lines) {
        if (line === 'data: [DONE]') continue;
        const data = JSON.parse(line.slice(6));
        const content = data.choices[0]?.delta?.content || '';
        process.stdout.write(content);
      }
    }
    ```
    {% endtab %}
    
    {% tab title="OpenAI SDK" %}
    ```python
    from openai import OpenAI
    
    client = OpenAI(
        api_key='YOUR_API_KEY',
        base_url='https://api.cortex.thegrid.ai/api/v1'
    )
    
    stream = client.chat.completions.create(
        model='chat-prime',
        messages=[{'role': 'user', 'content': 'Hello!'}],
        stream=True
    )
    
    for chunk in stream:
        content = chunk.choices[0].delta.content or ''
        print(content, end='', flush=True)
    ```
    {% endtab %}
    {% endtabs %}
    
    ## Rate Limits
    
    | Endpoint | Rate Limit |
    |----------|------------|
    | Chat Completions | 100 requests/minute |
    | List Models | 60 requests/minute |
    
    ## Common Error Codes
    
    | HTTP Status | Description |
    |-------------|-------------|
    | 400 | Bad Request - Invalid parameters |
    | 401 | Unauthorized - Invalid or missing API key |
    | 404 | Not Found - Model or resource not found |
    | 422 | Unprocessable Entity - Validation error |
    | 429 | Too Many Requests - Rate limit exceeded |
    | 500 | Internal Server Error |
    | 503 | Service Unavailable - Balance replenishing |
    
    {% hint style="info" %}
    **Balance Replenishing (503):** If you receive a `balance_replenishing` error, your account balance is being updated. Simply retry your request after a short delay.
    {% endhint %}
    
  version: "1.0.0"
  contact:
    name: Customer Support
    email: support@thegrid.ai
    url: "https://thegrid.ai/docs"
  license:
    name: Proprietary
  x-logo:
    url: "https://thegrid.ai/logo.png"
externalDocs:
  description: Full Documentation
  url: "https://thegrid.ai/docs"

servers:
  - url: https://api.cortex.thegrid.ai/api/v1
    description: Grid Consumption API

security:
  - bearerAuth: []

tags:
  - name: Chat Completions
    description: |
      Create chat completions using various LLM models. Compatible with the OpenAI chat completions API format.
  - name: Models
    description: |
      List available Grid Instruments that can be passed in the chat completions "model" field.

paths:
  /chat/completions:
    post:
      summary: Create chat completion
      description: |
        Creates a chat completion for the provided messages using the specified model. This endpoint is compatible with the OpenAI chat completions API format.
        
        The request is validated and then routed to the appropriate LLM provider. Your account balance is checked before processing.
      operationId: createChatCompletion
      tags: [Chat Completions]
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl -X POST 'https://api.cortex.thegrid.ai/api/v1/chat/completions' \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "model": "chat-prime",
                "messages": [
                  {"role": "system", "content": "Be concise and to the point."},
                  {"role": "user", "content": "Write one paragraph on why inference needs a market."}
                ],
                "max_tokens": 500
              }'
        - lang: Python
          source: |
            import requests
            
            response = requests.post(
                'https://api.cortex.thegrid.ai/api/v1/chat/completions',
                headers={
                    'Authorization': 'Bearer YOUR_API_KEY',
                    'Content-Type': 'application/json'
                },
                json={
                    'model': 'chat-prime',
                    'messages': [
                        {'role': 'system', 'content': 'Be concise and to the point.'},
                        {'role': 'user', 'content': 'Write one paragraph on why inference needs a market.'}
                    ],
                    'max_tokens': 500
                }
            )
            completion = response.json()
        - lang: JavaScript
          source: |
            const response = await fetch('https://api.cortex.thegrid.ai/api/v1/chat/completions', {
              method: 'POST',
              headers: {
                'Authorization': 'Bearer YOUR_API_KEY',
                'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                model: 'chat-prime',
                messages: [
                  { role: 'system', content: 'Be concise and to the point.' },
                  { role: 'user', content: 'Write one paragraph on why inference needs a market.' }
                ],
                max_tokens: 500
              })
            });
            const completion = await response.json();
        - lang: Python
          label: OpenAI SDK
          source: |
            from openai import OpenAI
            
            client = OpenAI(
                api_key='YOUR_API_KEY',
                base_url='https://api.cortex.thegrid.ai/api/v1'
            )
            
            completion = client.chat.completions.create(
                model='chat-prime',
                messages=[
                    {'role': 'system', 'content': 'Be concise and to the point.'},
                    {'role': 'user', 'content': 'Write one paragraph on why inference needs a market.'}
                ],
                max_tokens=500
            )
      security:
        - bearerAuth: []
      requestBody:
        description: Chat completion request parameters
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionsRequest"
            example:
              model: chat-prime
              messages:
                - role: system
                  content: Be concise and to the point.
                - role: user
                  content: Write one paragraph on why inference needs a market.
              max_tokens: 500
              temperature: 0.7
      responses:
        "200":
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"
              example:
                id: chatcmpl-abc123
                object: chat.completion
                created: 1677858242
                model: chat-prime
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: "Inference - the real‑time application of trained AI models to generate predictions, classifications, or recommendations - requires a market because its value is realized only when it can be delivered as a scalable, reliable service to end users. A market provides the economic incentives for developers to invest in optimizing hardware, software, and infrastructure that reduce latency, improve accuracy, and lower cost per query; it creates competition that drives innovation in model compression, edge deployment, and pricing models (pay‑per‑call, subscription, or platform‑as‑a‑service). Moreover, a market facilitates the aggregation of demand across diverse industries—healthcare, finance, retail, autonomous systems—allowing providers to achieve economies of scale, standardize APIs, and ensure compliance and security standards. Without such a marketplace, inference would remain a fragmented, research‑only capability, lacking the financial and operational mechanisms needed for widespread, sustainable adoption."
                    finish_reason: stop
                usage:
                  prompt_tokens: 25
                  completion_tokens: 18
                  total_tokens: 43
        "400":
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Invalid model specified"
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Invalid API key"
        "404":
          description: Not Found - Model not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Model not found"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - path: "messages"
                    message: "is required"
                    value: null
        "429":
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Rate limit exceeded. Please retry after 60 seconds."
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Internal server error"
        "503":
          description: |
            Service Unavailable - Balance replenishment in progress. Retry the request after a short delay.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BalanceError"
              example:
                error:
                  code: balance_replenishing
                  message: "Balance replenishment in progress. Please retry shortly."
                  type: balance_replenishing
                  param: null

  /models:
    get:
      summary: List available models
      description: |
        Returns a list of all available Grid Instruments that can be passed in the chat completions "model" field.
        
        Each instrument includes its ID, display name, and other metadata. Use the instrument `id` when making chat completion requests.
      operationId: listModels
      tags: [Models]
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl -X GET 'https://api.cortex.thegrid.ai/api/v1/models' \
              -H 'Authorization: Bearer YOUR_API_KEY'
        - lang: Python
          source: |
            import requests
            
            response = requests.get(
                'https://api.cortex.thegrid.ai/api/v1/models',
                headers={'Authorization': 'Bearer YOUR_API_KEY'}
            )
            models = response.json()['data']
        - lang: JavaScript
          source: |
            const response = await fetch('https://api.cortex.thegrid.ai/api/v1/models', {
              headers: {
                'Authorization': 'Bearer YOUR_API_KEY'
              }
            });
            const { data: models } = await response.json();
        - lang: Python
          label: OpenAI SDK
          source: |
            from openai import OpenAI
            
            client = OpenAI(
                api_key='YOUR_API_KEY',
                base_url='https://api.cortex.thegrid.ai/api/v1'
            )
            
            models = client.models.list()
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of available models
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelsResponse"
              example:
                object: list
                data:
                  - id: chat-prime
                    object: model
                    display_name: Chat Prime
                    created: 1687882411
                    owned_by: The Grid
                  - id: chat-standard
                    object: model
                    display_name: Chat Standard
                    created: 1706037777
                    owned_by: The Grid
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Invalid API key"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  detail: "Internal server error"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token authentication using your API key.
        
        Include your API key in the Authorization header:
        ```
        Authorization: Bearer YOUR_API_KEY
        ```
        
        Generate API keys from your [Grid Dashboard](https://app.thegrid.ai/profile/api-keys).

  schemas:
    ChatCompletionsRequest:
      title: ChatCompletionsRequest
      type: object
      required:
        - messages
      properties:
        model:
          type: string
          example: chat-prime
        messages:
          type: array
          minItems: 1
          items:
            oneOf:
              - $ref: "#/components/schemas/ChatCompletionSystemMessageParam"
              - $ref: "#/components/schemas/ChatCompletionDeveloperMessageParam"
              - $ref: "#/components/schemas/ChatCompletionUserMessageParam"
              - $ref: "#/components/schemas/ChatCompletionAssistantMessageParam"
              - $ref: "#/components/schemas/ChatCompletionToolMessageParam"
        max_tokens:
          type: integer
          minimum: 1
          nullable: true
          deprecated: true
        max_completion_tokens:
          type: integer
          minimum: 1
          nullable: true
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
          nullable: true
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          nullable: true
        n:
          type: integer
          minimum: 1
          maximum: 128
          default: 1
          nullable: true
        stream:
          type: boolean
          default: false
          nullable: true
        stream_options:
          type: object
          nullable: true
          properties:
            include_usage:
              type: boolean
            include_obfuscation:
              type: boolean
        stop:
          nullable: true
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 4
        logprobs:
          type: boolean
          default: false
          nullable: true
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
          nullable: true
        response_format:
          nullable: true
          oneOf:
            - $ref: "#/components/schemas/ResponseFormatText"
            - $ref: "#/components/schemas/ResponseFormatJSONObject"
            - $ref: "#/components/schemas/ResponseFormatJSONSchema"
        tools:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/ChatCompletionTool"
        tool_choice:
          nullable: true
          oneOf:
            - type: string
              enum: [none, auto, required]
            - $ref: "#/components/schemas/ChatCompletionNamedToolChoice"
        parallel_tool_calls:
          type: boolean
          default: true
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          nullable: true
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          nullable: true
        logit_bias:
          type: object
          additionalProperties:
            type: integer
            minimum: -100
            maximum: 100
          nullable: true
        seed:
          type: integer
          nullable: true
        service_tier:
          type: string
          enum: [auto, default, flex, scale, priority]
          nullable: true
        reasoning_effort:
          type: string
          enum: [none, minimal, low, medium, high, xhigh]
          nullable: true
        modalities:
          type: array
          nullable: true
          items:
            type: string
            enum: [text, audio]
        audio:
          type: object
          nullable: true
          properties:
            voice:
              oneOf:
                - type: string
                - type: string
                  enum: [alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar]
                - type: object
                  properties:
                    id:
                      type: string
            format:
              type: string
              enum: [wav, aac, mp3, flac, opus, pcm16]
        prediction:
          type: object
          nullable: true
          properties:
            type:
              type: string
              enum: [content]
            content:
              oneOf:
                - type: string
                - type: array
                  items:
                    $ref: "#/components/schemas/ChatCompletionContentPartText"
        metadata:
          type: object
          additionalProperties:
            type: string
            maxLength: 512
          nullable: true
        store:
          type: boolean
          nullable: true
        verbosity:
          type: string
          enum: [low, medium, high]
          nullable: true
        web_search_options:
          type: object
          nullable: true
          properties:
            search_context_size:
              type: string
              enum: [low, medium, high]
              default: medium
            user_location:
              type: object
              properties:
                type:
                  type: string
                  enum: [approximate]
                approximate:
                  type: object
                  properties:
                    city:
                      type: string
                    country:
                      type: string
                    region:
                      type: string
                    timezone:
                      type: string
        prompt_cache_key:
          type: string
          nullable: true
        prompt_cache_retention:
          type: string
          enum: [in-memory, 24h]
          nullable: true
        safety_identifier:
          type: string
          nullable: true
        route:
          type: string
          enum: [fallback]
        provider:
          type: object
        user:
          type: string
          deprecated: true
      example:
        model: chat-prime
        messages:
          - role: system
            content: Be concise and to the point.
          - role: user
            content: Write one paragraph on why inference needs a market.
        max_completion_tokens: 500
        temperature: 0.7

    ChatCompletionSystemMessageParam:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [system]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ChatCompletionContentPartText"
        name:
          type: string

    ChatCompletionDeveloperMessageParam:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [developer]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ChatCompletionContentPartText"
        name:
          type: string

    ChatCompletionUserMessageParam:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [user]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/ChatCompletionContentPartText"
                  - $ref: "#/components/schemas/ChatCompletionContentPartImage"
                  - $ref: "#/components/schemas/ChatCompletionContentPartInputAudio"
        name:
          type: string

    ChatCompletionAssistantMessageParam:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum: [assistant]
        content:
          nullable: true
          oneOf:
            - type: string
            - type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/ChatCompletionContentPartText"
                  - $ref: "#/components/schemas/ChatCompletionContentPartRefusal"
        name:
          type: string
        tool_calls:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionMessageToolCall"
        audio:
          type: object
          nullable: true
          properties:
            id:
              type: string

    ChatCompletionToolMessageParam:
      type: object
      required:
        - role
        - content
        - tool_call_id
      properties:
        role:
          type: string
          enum: [tool]
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: "#/components/schemas/ChatCompletionContentPartText"
        tool_call_id:
          type: string

    ChatCompletionContentPartText:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [text]
        text:
          type: string

    ChatCompletionContentPartImage:
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum: [image_url]
        image_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
            detail:
              type: string
              enum: [auto, low, high]
              default: auto

    ChatCompletionContentPartInputAudio:
      type: object
      required:
        - type
        - input_audio
      properties:
        type:
          type: string
          enum: [input_audio]
        input_audio:
          type: object
          required:
            - data
            - format
          properties:
            data:
              type: string
            format:
              type: string
              enum: [wav, mp3]

    ChatCompletionContentPartRefusal:
      type: object
      required:
        - type
        - refusal
      properties:
        type:
          type: string
          enum: [refusal]
        refusal:
          type: string

    ChatCompletionMessageToolCall:
      type: object
      required:
        - id
        - type
        - function
      properties:
        id:
          type: string
        type:
          type: string
          enum: [function]
        function:
          type: object
          required:
            - name
            - arguments
          properties:
            name:
              type: string
            arguments:
              type: string

    ChatCompletionTool:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum: [function]
        function:
          $ref: "#/components/schemas/FunctionDefinition"

    FunctionDefinition:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 64
        description:
          type: string
        parameters:
          type: object
        strict:
          type: boolean
          nullable: true

    ChatCompletionNamedToolChoice:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum: [function]
        function:
          type: object
          required:
            - name
          properties:
            name:
              type: string

    ResponseFormatText:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [text]

    ResponseFormatJSONObject:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum: [json_object]

    ResponseFormatJSONSchema:
      type: object
      required:
        - type
        - json_schema
      properties:
        type:
          type: string
          enum: [json_schema]
        json_schema:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              maxLength: 64
            description:
              type: string
            schema:
              type: object
            strict:
              type: boolean
              nullable: true

    ChatCompletionResponse:
      title: ChatCompletionResponse
      type: object
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
          example: chatcmpl-abc123
        object:
          type: string
          enum: [chat.completion]
        created:
          type: integer
          example: 1677858242
        model:
          type: string
          example: chat-prime
        system_fingerprint:
          type: string
          nullable: true
        service_tier:
          type: string
          enum: [auto, default, flex, scale, priority]
          nullable: true
        choices:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionChoice"
        usage:
          $ref: "#/components/schemas/CompletionUsage"
      example:
        id: chatcmpl-abc123
        object: chat.completion
        created: 1677858242
        model: chat-prime
        choices:
          - index: 0
            message:
              role: assistant
              content: The capital of France is Paris.
            finish_reason: stop
        usage:
          prompt_tokens: 25
          completion_tokens: 8
          total_tokens: 33

    ChatCompletionChoice:
      type: object
      required:
        - index
        - message
        - finish_reason
      properties:
        index:
          type: integer
        message:
          $ref: "#/components/schemas/ChatCompletionResponseMessage"
        logprobs:
          type: object
          nullable: true
          properties:
            content:
              type: array
              nullable: true
              items:
                $ref: "#/components/schemas/ChatCompletionTokenLogprob"
            refusal:
              type: array
              nullable: true
              items:
                $ref: "#/components/schemas/ChatCompletionTokenLogprob"
        finish_reason:
          type: string
          enum: [stop, length, tool_calls, content_filter, function_call]
          nullable: true

    ChatCompletionResponseMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum: [assistant]
        content:
          type: string
          nullable: true
        refusal:
          type: string
          nullable: true
        tool_calls:
          type: array
          items:
            $ref: "#/components/schemas/ChatCompletionMessageToolCall"
        audio:
          type: object
          nullable: true
          properties:
            id:
              type: string
            expires_at:
              type: integer
            data:
              type: string
            transcript:
              type: string

    ChatCompletionTokenLogprob:
      type: object
      required:
        - token
        - logprob
        - bytes
        - top_logprobs
      properties:
        token:
          type: string
        logprob:
          type: number
        bytes:
          type: array
          nullable: true
          items:
            type: integer
        top_logprobs:
          type: array
          items:
            type: object
            required:
              - token
              - logprob
              - bytes
            properties:
              token:
                type: string
              logprob:
                type: number
              bytes:
                type: array
                nullable: true
                items:
                  type: integer

    CompletionUsage:
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        prompt_tokens_details:
          type: object
          nullable: true
          properties:
            cached_tokens:
              type: integer
            audio_tokens:
              type: integer
        completion_tokens_details:
          type: object
          nullable: true
          properties:
            reasoning_tokens:
              type: integer
            audio_tokens:
              type: integer
            accepted_prediction_tokens:
              type: integer
            rejected_prediction_tokens:
              type: integer

    ErrorResponse:
      title: ErrorResponse
      description: Error response returned when a request fails
      type: object
      required:
        - errors
      properties:
        errors:
          description: |
            Error details. Can be either:
            - An object with a `detail` field for general errors
            - An array of validation errors with `path`, `message`, and `value` fields
          oneOf:
            - type: object
              required:
                - detail
              properties:
                detail:
                  type: string
                  description: Human-readable error message
            - type: array
              description: List of validation errors
              items:
                type: object
                required:
                  - path
                  - message
                properties:
                  path:
                    type: string
                    description: The field path that caused the error
                  message:
                    type: string
                    description: Description of the validation error
                  value:
                    type: string
                    description: The invalid value that was provided
      example:
        errors:
          detail: "Invalid API key provided"

    BalanceError:
      title: BalanceError
      description: Error response for balance-related issues (e.g., replenishment in progress)
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - type
          properties:
            code:
              type: string
              description: Error code identifier
              example: balance_replenishing
            message:
              type: string
              description: Human-readable error message
              example: "Balance replenishment in progress. Please retry shortly."
            type:
              type: string
              description: Error type classification
              example: balance_replenishing
            param:
              type: string
              nullable: true
              description: The parameter that caused the error, if applicable
              example: null
      example:
        error:
          code: balance_replenishing
          message: "Balance replenishment in progress. Please retry shortly."
          type: balance_replenishing
          param: null

    ModelsResponse:
      title: ModelsResponse
      description: List of available models
      type: object
      required:
        - object
        - data
      properties:
        object:
          type: string
          description: The object type, always "list"
          enum: [list]
        data:
          type: array
          description: List of model objects
          items:
            $ref: "#/components/schemas/Model"
      example:
        object: list
        data:
          - id: chat-prime
            object: model
            display_name: Chat Prime
            created: 1687882411
            owned_by: The Grid
          - id: chat-standard
            object: model
            display_name: Chat Standard
            created: 1709251200
            owned_by: The Grid

    Model:
      title: Model
      description: An LLM model available for use
      type: object
      properties:
        id:
          type: string
          description: |
            The model identifier to use in API requests.
            Format is typically `provider/model-name`.
          example: chat-prime
        object:
          type: string
          description: The object type, always "model"
          enum: [model]
        display_name:
          type: string
          description: Human-readable name for the model
          example: Chat Prime
        created:
          type: integer
          description: Unix timestamp when the model was created
          example: 1687882411
        owned_by:
          type: string
          description: The organization that owns the model
          example: The Grid
