openapi: 3.0.3
info:
  title: SupaNexus OpenAPI Gateway
  description: |-
    OpenAI-compatible API for SupaNexus.

    Authenticate with `Authorization: Bearer <API Key>`. All `/v1/*` endpoints
    require a valid project API key (format `sk-snx-...`). Responses follow OpenAI JSON shapes; SupaNexus
    adds `X-SNX-Trace-ID`, `X-SNX-Model`, and `X-SNX-Provider` on chat
    completions.

    Two production endpoints share the same account, API key, paths, models, and billing:
    Global (`https://api.supanexus.ai`) and CN backup (`https://api.supanexus.io`).

    Embeddings and image generation routes return HTTP 501 until announced.

    Generated (UTC): 2026-08-07T07:15:26Z
  version: 1.0.0
servers:
  - url: https://api.supanexus.ai
    description: SupaNexus OpenAPI gateway (production, Global)
  - url: https://api.supanexus.io
    description: SupaNexus OpenAPI gateway (CN backup)
tags:
  - name: GatewayOpenAPI
    description: OpenAI-compatible API (Bearer API Key)
  - name: Probes
    description: Health and readiness probes
components:
  securitySchemes:
    BearerAPIKey:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'Project API key. Use `Authorization: Bearer <your-api-key>`.'
  parameters:
    HeaderXLocale:
      name: X-Locale
      in: header
      required: false
      schema:
        type: string
      description: 优先于 Accept-Language（SupaNexus API）
    HeaderAcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
      description: i18n 语言回退
  schemas:
    WhaleErrorEnvelope:
      type: object
      required:
        - code
        - message
        - data
        - timestamp
      properties:
        code:
          type: string
        message:
          type: string
        data:
          nullable: true
        timestamp:
          type: integer
          format: int64
    OpenAIErrorBody:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              description: HTTP status code (OpenRouter-compatible)
            message:
              type: string
            metadata:
              type: object
              additionalProperties: true
    OpenAIListModelsResponse:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/OpenAIModel'
    OpenAIModel:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
          format: int64
        owned_by:
          type: string
    ChatCompletionRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
        stream:
          type: boolean
          default: false
        messages:
          type: array
          items: {}
paths:
  /healthz:
    get:
      tags:
        - Probes
      summary: 存活探针
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  service:
                    type: string
  /readyz:
    get:
      tags:
        - Probes
      summary: 就绪探针
      responses:
        '200':
          description: 依赖可用
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  service:
                    type: string
        '503':
          description: 依赖不可用
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  error:
                    type: string
  /v1/models:
    get:
      tags:
        - GatewayOpenAPI
      operationId: openApiListModels
      summary: 列出模型
      security:
        - BearerAPIKey: []
      parameters:
        - $ref: '#/components/parameters/HeaderXLocale'
        - $ref: '#/components/parameters/HeaderAcceptLanguage'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIListModelsResponse'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: Model service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
  /v1/models/{id}:
    get:
      tags:
        - GatewayOpenAPI
      operationId: openApiRetrieveModel
      summary: 获取模型
      security:
        - BearerAPIKey: []
      parameters:
        - $ref: '#/components/parameters/HeaderXLocale'
        - $ref: '#/components/parameters/HeaderAcceptLanguage'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIModel'
        '400':
          description: 错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '404':
          description: 未找到
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: Model service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
  /v1/chat/completions:
    post:
      tags:
        - GatewayOpenAPI
      operationId: openApiChatCompletions
      summary: Chat Completions（支持流式 SSE）
      security:
        - BearerAPIKey: []
      parameters:
        - $ref: '#/components/parameters/HeaderXLocale'
        - $ref: '#/components/parameters/HeaderAcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: 非流式 JSON 或流式 text/event-stream
          headers:
            X-SNX-Model:
              schema:
                type: string
            X-SNX-Provider:
              schema:
                type: string
            X-SNX-Trace-ID:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: 错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '402':
          description: 余额不足
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '404':
          description: 未知模型
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '408':
          description: 请求超时
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: Model service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '503':
          description: 无可用 Provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '504':
          description: 请求超时（已废弃，请用 408）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
  /v1/messages:
    post:
      tags:
        - GatewayOpenAPI
      operationId: openApiMessages
      summary: Messages（Anthropic 兼容，支持流式 SSE）
      security:
        - BearerAPIKey: []
      parameters:
        - $ref: '#/components/parameters/HeaderXLocale'
        - $ref: '#/components/parameters/HeaderAcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnthropicMessagesRequest'
      responses:
        '200':
          description: Anthropic message JSON 或流式 event-stream
          headers:
            X-SNX-Model:
              schema:
                type: string
            X-SNX-Provider:
              schema:
                type: string
            X-SNX-Trace-ID:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Anthropic 错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
        '402':
          description: 余额不足
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
        '404':
          description: 未知模型
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
        '408':
          description: 请求超时
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: 服务暂时不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
        '503':
          description: 无可用 Provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicErrorBody'
  /v1/embeddings:
    post:
      tags:
        - GatewayOpenAPI
      operationId: openApiEmbeddings
      summary: Embeddings（PRD backlog，当前返回 501）
      security:
        - BearerAPIKey: []
      parameters:
        - $ref: '#/components/parameters/HeaderXLocale'
        - $ref: '#/components/parameters/HeaderAcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
  /v1/images/generations:
    post:
      tags:
        - GatewayOpenAPI
      operationId: openApiImagesGenerations
      summary: Images generations（PRD backlog，当前返回 501）
      security:
        - BearerAPIKey: []
      parameters:
        - $ref: '#/components/parameters/HeaderXLocale'
        - $ref: '#/components/parameters/HeaderAcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorBody'