Yunqi AI Gateway API

openapi: 3.1.0
info:
  title: ClickZetta AI Gateway API
  version: 2.0.0
  summary: 用一个 API Key 统一调用多家云厂商的大模型。
  description: |
    AI Gateway 提供兼容 OpenAI Chat Completions、Anthropic Messages 和火山引擎多模态 Embedding 协议的统一入口，
    负责鉴权、按服务档位路由到上游供应商、用量统计和计费。

    ## 认证
    使用在 AI Gateway“API Key 管理”中创建的 API Key，不要使用云厂商的原始 Key。
    OpenAI 协议和火山引擎协议使用 `Authorization: Bearer <API_KEY>`，Anthropic 协议使用 `x-api-key: <API_KEY>`。
    每个 API Key 绑定一个服务档位（经济型、标准型、高质量型），档位不可用时不会自动切换到其他档位。

    ## 路径
    - 腾讯 TokenHub 等文本模型使用 `/gateway/v1/...`，不要写成 `/gateway/api/v1/...`。
    - 火山引擎模型使用 `/gateway/api/v3/...`，不要和 `/gateway/v1` 混用。
    - 模型名称以产品“模型广场”详情页为准，例如 `deepseek-v4-flash`、`deepseek-v4-pro`、`doubao-embedding-vision`。

    ## 错误
    错误响应统一为 `{ "error": { "code", "message", "source", "retry_history" } }`。请以 `code` 作为程序判断依据，不要解析 `message` 文本。
    `source=gateway` 表示请求在到达任何模型前被网关拦截；`source=upstream` 表示请求已转发，但所有上游端点都失败，此时 `retry_history` 记录每次尝试。
    400、401、403 不建议直接重试，应先修正请求、API Key 或账务配额；429 可以指数退避重试并降低并发；500、502 可以稍后重试。
    视频、图片、3D 等异步任务的创建接口不要盲目自动重试，建议在业务侧使用幂等键。
  contact:
    name: Singdata
    email: service@yunqi.tech
    url: https://www.yunqi.tech/documents/AIGateway
  termsOfService: https://www.yunqi.tech/documents/user-agreement
externalDocs:
  description: AI Gateway 文档
  url: https://www.yunqi.tech/documents/AIGateway
servers:
  - url: https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway
    description: 文档所列的 AI Gateway 接入地址（国内 SaaS）
tags:
  - name: Chat
    description: 兼容 OpenAI Chat Completions 和 Anthropic Messages 协议的对话生成。
    externalDocs:
      url: https://www.yunqi.tech/documents/aigw_tencent_deepseek_openai_calling
  - name: Embeddings
    description: 兼容火山引擎协议的多模态向量化。
    externalDocs:
      url: https://www.yunqi.tech/documents/aigw_volcengine_embedding_calling

paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      summary: 对话生成（OpenAI Chat Completions 兼容）
      description: 按 OpenAI Chat Completions 协议调用对话模型。设置 `stream=true` 时以 SSE（text/event-stream）逐段返回。多轮对话需要回传历史消息，历史中的 assistant 消息一般只需要 `content`。
      tags: [Chat]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: 基础对话
                value:
                  model: deepseek-v4-flash
                  messages:
                    - { role: user, content: 请介绍一下大语言模型。 }
                  max_tokens: 1024
                  thinking: { type: disabled }
              streaming:
                summary: 流式输出并开启思考
                value:
                  model: deepseek-v4-pro
                  messages:
                    - { role: user, content: 请介绍一下大语言模型。 }
                  stream: true
                  stream_options: { include_usage: true }
                  thinking: { type: enabled, reasoning_effort: high }
      responses:
        '200':
          description: 生成成功。非流式返回 JSON，流式返回 SSE 事件流。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              example:
                id: chatcmpl-xxx
                object: chat.completion
                created: 1710000000
                model: deepseek-v4-flash
                choices:
                  - index: 0
                    message: { role: assistant, content: AI Gateway 可以统一管理模型调用、鉴权、路由和用量统计。 }
                    finish_reason: stop
                usage: { prompt_tokens: 32, completion_tokens: 24, total_tokens: 56 }
            text/event-stream:
              schema:
                type: string
                description: SSE 事件流，客户端需要逐段读取。文本在 `choices[0].delta.content`；开启思考时，delta 中可能同时包含 `reasoning_content` 和 `content`。不展示推理过程时只渲染 `content`。
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '502': { $ref: '#/components/responses/UpstreamFailed' }

  /v1/messages:
    post:
      operationId: createMessage
      summary: 对话生成（Anthropic Messages 兼容）
      description: 按 Anthropic Messages 协议调用对话模型，可以直接使用 Anthropic SDK。`thinking`、`top_k`、`metadata`、`service_tier`、`cache_control`、`disable_parallel_tool_use` 会被忽略；不支持 `document` 和 `search_result` 类型的内容块。
      tags: [Chat]
      security:
        - apiKeyHeader: []
      parameters:
        - name: anthropic-version
          in: header
          required: false
          description: Anthropic 协议版本。上游会忽略该值，保留它是为了兼容 Anthropic SDK 和常见客户端。
          schema: { type: string, examples: ['2023-06-01'] }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            example:
              model: deepseek-v4-pro
              max_tokens: 1000
              stream: false
              system: 你是一个专业、准确、简洁的企业 AI 助手。
              messages:
                - { role: user, content: 请解释 OpenAI Chat Completions 和 Anthropic Messages 的区别。 }
      responses:
        '200':
          description: 生成成功。非流式返回 Anthropic Message 对象，流式返回 SSE 事件流。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
            text/event-stream:
              schema:
                type: string
                description: Anthropic Messages 兼容的 SSE 事件流。
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '502': { $ref: '#/components/responses/UpstreamFailed' }

  /api/v3/embeddings/multimodal:
    post:
      operationId: createMultimodalEmbedding
      summary: 多模态向量化（火山引擎协议兼容）
      description: 把文本、图片 URL 或视频 URL 转换为向量。建库和查询必须使用同一模型和同一维度；图片和视频 URL 必须可公开访问；单次请求的批量不宜过大。
      tags: [Embeddings]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultimodalEmbeddingRequest'
            example:
              model: doubao-embedding-vision
              input:
                - { type: text, text: AI Gateway 支持统一模型调用、路由和用量统计。 }
              encoding_format: float
              dimensions: 1024
      responses:
        '200':
          description: 向量化成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
              example:
                object: list
                data:
                  - { object: embedding, index: 0, embedding: [0.0123, -0.0456, 0.0789] }
                model: doubao-embedding-vision
                usage: { prompt_tokens: 32, total_tokens: 32 }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
        '500': { $ref: '#/components/responses/InternalError' }
        '502': { $ref: '#/components/responses/UpstreamFailed' }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 在 AI Gateway“API Key 管理”中创建的 API Key，用于 OpenAI 协议和火山引擎协议。不要使用云厂商原始 Key。
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 在 AI Gateway“API Key 管理”中创建的 API Key，用于 Anthropic Messages 协议。

  responses:
    BadRequest:
      description: 请求格式、路径、模型或路由参数有误。不建议直接重试，应先修正请求。
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GatewayErrorResponse' }
          example:
            error: { code: GATEWAY_MODEL_NOT_RESOLVED, message: '[G2] ... requestId=...', source: gateway }
    Unauthorized:
      description: 鉴权失败。不建议直接重试，应检查 API Key 是否来自 AI Gateway、是否存在、是否已停用。
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GatewayErrorResponse' }
          example:
            error: { code: GATEWAY_MISSING_VIRTUAL_KEY, message: '[G2] Virtual key not provided. path=/v1/chat/completions, requestId=...', source: gateway }
    Forbidden:
      description: 账务、配额或权限问题。不建议直接重试，应结清账单、等待下一计费周期或申请提升配额。
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GatewayErrorResponse' }
          example:
            error: { code: GATEWAY_TENANT_OVER_QUOTA, message: '[G2] ... requestId=...', source: gateway }
    TooManyRequests:
      description: 请求频率或并发超过限制。可以指数退避重试，并降低并发。
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GatewayErrorResponse' }
    InternalError:
      description: 网关内部异常。可以稍后重试，持续出现请联系支持，并提供 requestId、API Key 名称、模型名称、请求时间和错误响应。
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GatewayErrorResponse' }
          example:
            error: { code: GATEWAY_INTERNAL_API_EXCEPTION, message: '[G2] ... requestId=...', source: gateway }
    UpstreamFailed:
      description: 所有候选上游端点都返回错误或不可达。可以稍后重试；持续出现时检查 retry_history 中各上游的状态码。
      content:
        application/json:
          schema: { $ref: '#/components/schemas/GatewayErrorResponse' }
          example:
            error:
              code: UPSTREAM_ALL_FAILED
              message: '[G2] ... requestId=...'
              source: upstream
              retry_history:
                - { base_url: 'https://dashscope.aliyuncs.com/compatible-mode/v1', status: 429, body: '...' }

  schemas:
    GatewayErrorResponse:
      type: object
      description: AI Gateway 统一错误响应。
      required: [error]
      properties:
        error:
          $ref: '#/components/schemas/GatewayError'

    GatewayError:
      type: object
      description: 错误详情。
      required: [code, message, source]
      properties:
        code:
          $ref: '#/components/schemas/GatewayErrorCode'
        message:
          type: string
          description: 可读的错误描述，通常包含 requestId 等排查信息。开头的 [G2] 是内部追踪标记，可以忽略。
        source:
          type: string
          enum: [gateway, upstream]
          description: gateway 表示请求未到达任何模型即被拦截；upstream 表示请求已转发，但所有上游端点均失败。
        retry_history:
          type: [array, 'null']
          description: source=upstream 时记录每个上游端点的尝试结果，其他情况通常为 null。
          items:
            $ref: '#/components/schemas/UpstreamAttempt'

    GatewayErrorCode:
      type: string
      description: |
        机器可读的错误码：
        - `GATEWAY_MISSING_VIRTUAL_KEY`（401）：请求中未提供虚拟密钥
        - `GATEWAY_INVALID_VIRTUAL_KEY`（401）：虚拟密钥不存在或格式不正确
        - `GATEWAY_VIRTUAL_KEY_DISABLED`（401）：虚拟密钥已被停用
        - `GATEWAY_TENANT_OVERDUE`（403）：租户存在未结清账单，调用已暂停
        - `GATEWAY_TENANT_OVER_QUOTA`（403）：租户超出当前计费周期的用量配额
        - `GATEWAY_MISSING_ACTUAL_PATH`（400）：无法从请求 URL 解析出转发路径
        - `GATEWAY_MODEL_NOT_RESOLVED`（400）：无法从请求体确定要路由的模型
        - `GATEWAY_NO_UPSTREAM_CANDIDATES`（400）：该模型和协议组合没有可用的上游端点
        - `GATEWAY_INTERNAL_ENDPOINTS_BAD_REQUEST`（400）：调用内部端点接口时缺少必填字段
        - `GATEWAY_INTERNAL_API_EXCEPTION`（500）：网关内部接口发生未预期异常
        - `UPSTREAM_ALL_FAILED`（502）：所有候选上游端点均返回错误或不可达
      enum:
        - GATEWAY_MISSING_VIRTUAL_KEY
        - GATEWAY_INVALID_VIRTUAL_KEY
        - GATEWAY_VIRTUAL_KEY_DISABLED
        - GATEWAY_TENANT_OVERDUE
        - GATEWAY_TENANT_OVER_QUOTA
        - GATEWAY_MISSING_ACTUAL_PATH
        - GATEWAY_MODEL_NOT_RESOLVED
        - GATEWAY_NO_UPSTREAM_CANDIDATES
        - GATEWAY_INTERNAL_ENDPOINTS_BAD_REQUEST
        - GATEWAY_INTERNAL_API_EXCEPTION
        - UPSTREAM_ALL_FAILED

    UpstreamAttempt:
      type: object
      description: 一次上游尝试的记录。
      properties:
        endpoint_id: { type: string, description: 上游端点 ID。 }
        slug_name: { type: string, description: 上游端点标识。 }
        base_url: { type: string, description: 上游地址。 }
        api_key_alias: { type: string, description: 所用上游密钥的别名。 }
        provider: { type: string, description: 上游供应商。 }
        model: { type: string, description: 上游模型名。 }
        status: { type: integer, description: 上游返回的 HTTP 状态码，例如 429。 }
        body: { type: string, description: 上游返回的原始错误报文，可能被截断。 }

    ChatMessage:
      type: object
      description: 一条对话消息。
      required: [role]
      properties:
        role: { type: string, examples: [system, user, assistant], description: 消息角色。 }
        content: { description: 消息内容。 }
        reasoning_content: { type: string, description: 开启思考时模型可能返回的推理内容。多轮对话回传历史时，assistant 消息一般只需要 content。 }

    ChatCompletionRequest:
      type: object
      description: OpenAI Chat Completions 兼容请求。
      required: [model, messages]
      properties:
        model: { type: string, description: 模型名称，以模型广场详情页为准，例如 deepseek-v4-flash。 }
        messages: { type: array, items: { $ref: '#/components/schemas/ChatMessage' }, description: 按时间顺序排列的消息。 }
        stream: { type: boolean, default: false, description: 是否以 SSE 流式返回。 }
        stream_options:
          type: object
          description: 流式选项，仅在 stream=true 时生效。
          properties:
            include_usage: { type: boolean, description: 是否在流末尾返回用量。 }
        temperature: { type: number, minimum: 0, maximum: 2, description: 采样温度，和 top_p 二选一调整。 }
        top_p: { type: number, minimum: 0, maximum: 1, description: 核采样概率，和 temperature 二选一调整。 }
        max_tokens: { type: integer, description: 最大输出 Token 数，思考 Token 和回答 Token 共用该额度。 }
        n: { type: integer, default: 1, description: 生成候选数，大于 1 时按总 Token 计费。 }
        stop: { description: 停止序列，字符串或字符串数组。 }
        response_format:
          type: object
          description: 输出格式，例如 {"type":"json_object"}。不建议与 thinking.type=enabled 同时使用。
          properties:
            type: { type: string }
        tools: { type: array, items: { type: object }, description: 工具定义。 }
        tool_choice: { description: 'auto、none、required 或指定工具。' }
        parallel_tool_calls: { type: boolean, description: 是否允许并行工具调用。 }
        thinking:
          type: object
          description: 思考模式配置。
          properties:
            type: { type: string, enum: [enabled, disabled] }
            reasoning_effort: { type: string, description: 思考强度，例如 high。 }

    ChatCompletionResponse:
      type: object
      description: OpenAI Chat Completions 兼容响应。
      properties:
        id: { type: string }
        object: { type: string, examples: [chat.completion] }
        created: { type: integer, description: Unix 时间戳（秒）。 }
        model: { type: string }
        choices:
          type: array
          items:
            type: object
            properties:
              index: { type: integer }
              message: { $ref: '#/components/schemas/ChatMessage' }
              finish_reason: { type: string, examples: [stop, length, tool_calls], description: 结束原因。 }
        usage:
          $ref: '#/components/schemas/Usage'

    MessageRequest:
      type: object
      description: Anthropic Messages 兼容请求。
      required: [model, messages, max_tokens]
      properties:
        model: { type: string, description: 模型名称，例如 deepseek-v4-pro。 }
        max_tokens: { type: integer, description: 最大输出 Token 数。 }
        system: { description: 系统提示词，字符串或 text 内容块数组。 }
        messages:
          type: array
          description: 对话消息。content 支持字符串和 text 内容块，部分模型支持 image。
          items:
            type: object
            properties:
              role: { type: string, enum: [user, assistant] }
              content: { description: 字符串或内容块数组。 }
        stream: { type: boolean, default: false }
        temperature: { type: number, minimum: 0, maximum: 2 }
        top_p: { type: number }
        stop_sequences: { type: array, items: { type: string } }
        tools:
          type: array
          description: 工具定义，包含 name、description 和 input_schema。
          items: { type: object }
        tool_choice: { description: '字符串或对象形式，例如 {"type":"auto"}。' }

    MessageResponse:
      type: object
      description: Anthropic Messages 兼容响应，可以直接用 Anthropic SDK 解析，文本在 content[0].text。其他字段以 Anthropic SDK 实际返回为准，本合同不逐一约束。
      properties:
        content:
          type: array
          description: 内容块。
          items:
            type: object
            properties:
              text: { type: string, description: 文本内容。 }

    MultimodalEmbeddingRequest:
      type: object
      description: 多模态向量化请求。
      required: [model, input]
      properties:
        model: { type: string, description: 向量模型名称，例如 doubao-embedding-vision。 }
        input:
          type: array
          description: 待向量化的内容。
          items:
            description: 一项输入内容，按 type 区分文本、图片和视频。
            oneOf:
              - type: object
                title: 文本
                required: [type, text]
                properties:
                  type: { const: text }
                  text: { type: string, description: 文本内容。 }
              - type: object
                title: 图片
                required: [type, image_url]
                properties:
                  type: { const: image_url }
                  image_url:
                    type: object
                    required: [url]
                    properties:
                      url: { type: string, format: uri, description: 图片 URL，必须可公开访问。 }
              - type: object
                title: 视频
                required: [type, video_url]
                properties:
                  type: { const: video_url }
                  video_url:
                    type: object
                    required: [url]
                    properties:
                      url: { type: string, format: uri, description: 视频 URL，必须可公开访问。 }
        encoding_format: { type: string, examples: [float], description: 向量编码格式。 }
        dimensions: { type: integer, description: 输出向量维度，建库后不要修改。 }

    EmbeddingResponse:
      type: object
      description: 向量化响应。
      properties:
        object: { type: string, examples: [list] }
        data:
          type: array
          items:
            type: object
            properties:
              object: { type: string, examples: [embedding] }
              index: { type: integer }
              embedding: { type: array, items: { type: number } }
        model: { type: string }
        usage:
          $ref: '#/components/schemas/Usage'

    Usage:
      type: object
      description: Token 用量。completion_tokens 可能包含思考 Token。
      properties:
        prompt_tokens: { type: integer }
        completion_tokens: { type: integer }
        total_tokens: { type: integer }