> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokengift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a chat completion

> OpenAI Chat Completions-compatible endpoint (curated subset).
Supports streaming (`stream: true`) via server-sent events.
Cost is reserved up-front from the app wallet and settled to actual usage.




## OpenAPI

````yaml /api-reference/openapi.yaml post /chat/completions
openapi: 3.1.0
info:
  title: TokenGift API
  version: '2026-07-29'
  description: |
    OpenAI-compatible inference API funded by gift cards and top-ups.
    Point any OpenAI SDK at `https://api.tokengift.ai/v1`.
servers:
  - url: https://api.tokengift.ai/v1
security:
  - bearerAuth: []
paths:
  /chat/completions:
    post:
      summary: Create a chat completion
      description: >
        OpenAI Chat Completions-compatible endpoint (curated subset).

        Supports streaming (`stream: true`) via server-sent events.

        Cost is reserved up-front from the app wallet and settled to actual
        usage.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - messages
              properties:
                model:
                  type: string
                  description: Curated model ID (see Models & pricing).
                  examples:
                    - openai/gpt-4o-mini
                messages:
                  type: array
                  description: OpenAI-format message list.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                      content:
                        type: string
                max_tokens:
                  type: integer
                  description: >-
                    Output token cap. Defaults to 2048 if omitted (used for cost
                    reservation).
                stream:
                  type: boolean
                  description: Stream the response as SSE.
      responses:
        '200':
          description: Completion (OpenAI-compatible shape). Streaming responses are SSE.
          headers:
            TokenGift-Balance:
              schema:
                type: string
              description: Wallet balance (USD) after this request.
            TokenGift-Request-Cost:
              schema:
                type: string
              description: Exact cost (USD) of this request (non-streaming).
            TokenGift-Request-Id:
              schema:
                type: string
              description: Request ID for support/debugging.
          content:
            application/json:
              schema:
                type: object
                description: OpenAI-compatible chat completion object.
        '400':
          description: Invalid request (bad JSON, missing or unknown model).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits. The error body includes the app's top-up URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '429':
          description: Rate limit exceeded. Back off for `Retry-After` seconds.
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds until the rate limit window resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Upstream provider unreachable. Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Broad category (OpenAI-compatible taxonomy).
              examples:
                - authentication_error
                - invalid_request_error
                - rate_limit_error
            code:
              type: string
              description: Stable machine-readable identifier — branch on this.
              examples:
                - invalid_api_key
                - model_not_found
                - rate_limit_exceeded
            message:
              type: string
            param:
              type: string
              description: Present when the error is about a specific request field.
            doc_url:
              type: string
              description: Deep link to the matching section of the error docs.
    InsufficientCreditsError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              const: insufficient_credits
            code:
              type: string
              const: insufficient_credits
            message:
              type: string
            doc_url:
              type: string
            balance:
              type: string
              description: Current wallet balance (USD).
            top_up_url:
              type: string
              description: Hosted top-up page for this app — show it to your users.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: App API key (tg_live_…)

````