openapi: 3.1.0
info:
  title: AI Inference & Embeddings Gateway
  summary: Unified OpenAPI 3.1 specification for multimodal chat completions, embeddings, and model routing
  description: |
    Standardized inference router supporting structured JSON outputs, token usage budgets, and vector embeddings.
  version: 1.2.0
  license:
    name: MIT
    identifier: MIT
servers:
  - url: /api/mock/ai-inference-gateway
    description: Built-in OpenAPI 3.1 Mock Server
  - url: https://httpbin.org/anything
    description: Echo Inspection Endpoint
tags:
  - name: Completions
    description: Generate text and structured outputs
  - name: Embeddings
    description: Generate dense vector representations
  - name: Models
    description: Inspect available foundation models
paths:
  /v1/models:
    get:
      operationId: listModels
      summary: List available foundation models
      tags:
        - Models
      responses:
        '200':
          description: List of active models and context window limits
          content:
            application/json:
              schema:
                type: object
                properties:
                  models:
                    type: array
                    items:
                      $ref: '#/components/schemas/ModelCard'
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: Create a model chat completion
      tags:
        - Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Generated completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
  /v1/embeddings:
    post:
      operationId: createEmbeddings
      summary: Generate vector embeddings
      tags:
        - Embeddings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  examples: ['text-embedding-3-large']
                input:
                  type: string
                  examples: ['OpenAPI 3.1 unifies OAS with JSON Schema 2020-12']
                dimensions:
                  type: ['integer', 'null']
                  examples: [1536]
      responses:
        '200':
          description: Embedding vector array
          content:
            application/json:
              schema:
                type: object
                properties:
                  model:
                    type: string
                    examples: ['text-embedding-3-large']
                  embedding:
                    type: array
                    items:
                      type: number
                    examples: [[0.0231, -0.0144, 0.0892, 0.0412]]
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    ModelCard:
      type: object
      required:
        - id
        - provider
        - contextWindow
      properties:
        id:
          type: string
          examples: ['gemini-4-argon']
        provider:
          type: string
          examples: ['google-deepmind']
        contextWindow:
          type: integer
          examples: [1000000]
        supportsVision:
          type: boolean
          default: true
        deprecationDate:
          type: ['string', 'null']
          examples: [null]
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          examples: ['gemini-4-argon']
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.7
        maxTokens:
          type: ['integer', 'null']
          examples: [1024]
        messages:
          type: array
          items:
            type: object
            required:
              - role
              - content
            properties:
              role:
                type: string
                enum: [system, user, assistant]
                examples: ['user']
              content:
                type: string
                examples: ['Explain the key differences between OpenAPI 3.0 and 3.1.']
    ChatCompletionResponse:
      type: object
      required:
        - id
        - model
        - reply
        - usage
      properties:
        id:
          type: string
          examples: ['chatcmpl_99281a']
        model:
          type: string
          examples: ['gemini-4-argon']
        reply:
          type: string
          examples: ['OpenAPI 3.1 achieves 100% compatibility with JSON Schema Draft 2020-12, adds top-level webhooks, and replaces nullable with type arrays.']
        usage:
          type: object
          properties:
            promptTokens:
              type: integer
              examples: [24]
            completionTokens:
              type: integer
              examples: [48]