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

# 使用 Viggle-Animate

> 使用 Viggle-Animate，将驱动视频的动作和角色图片生成为视频。

使用 `multipart/form-data` 或 `application/json` 提交请求，至少通过 `character_image_url` 或 `character_image_urls` 提供一张角色图片，也可同时提供 `driving_video_url`。这三个字段会选择 `POST /v1/videos` 的角色动画模式，由 Viggle-Animate 处理，与该接口的其他四种模式使用不同的后端。

<Note>
  角色动画模式不接受文件上传。`driving_video_url` 和角色图片都必须已经可以通过 URL（`https://` 或内部 `gs://` 对象）访问。它也是唯一支持普通 JSON 请求体的模式，详见下方 [JSON 请求体](#json-request-body)。
</Note>

本模式与[文本生成视频](/zh/v1/api-reference/videos/create-from-text)、[首帧生成视频](/zh/v1/api-reference/videos/create-from-first-frame)、[首尾帧生成视频](/zh/v1/api-reference/videos/create-from-first-last-frame)和[参考素材生成视频](/zh/v1/api-reference/videos/create-from-reference-video)共用 `POST /v1/videos`。模式由请求字段决定，无需单独的选择参数。角色动画字段不能与 `quality` 或其他模式的帧、参考素材字段混用，否则返回 `400 INVALID_REQUEST`，例如 "driving\_video\_url/character\_image\_url cannot be combined with quality"。

<Warning>
  每次请求固定收取 **11 积分（\$0.11）**，与实际输出时长无关。本模式不支持 `quality`、`duration_s`、`resolution`、`aspect_ratio` 或 `seed`。详见下方计费说明。
</Warning>

## 请求参数

使用 `multipart/form-data` 或 JSON。

| 参数                     | 类型               |  必填 | 默认值     | 说明                                                                                                          |
| ---------------------- | ---------------- | :-: | ------- | ----------------------------------------------------------------------------------------------------------- |
| `driving_video_url`    | string (URI)     |  否  | —       | 驱动视频 URL，其动作将应用到角色图片。支持 `https://` 或内部 `gs://`，仅可提供一个值。视频须为 5–10 秒（含边界）、至少 64×64 像素，且宽高均为偶数。                |
| `character_image_url`  | string (URI)，可重复 | 见下文 | —       | 角色参考图片 URL，可重复。与 `character_image_urls` 互斥。                                                                 |
| `character_image_urls` | string (URI) 数组  | 见下文 | —       | 与 `character_image_url` 等效，但将多个值放入一个字段。multipart 中使用 JSON 字符串数组，JSON 请求体中使用原生数组。与 `character_image_url` 互斥。 |
| `prompt`               | string           |  否  | —       | 可选的风格或内容提示，不要求必填，也不强制非空。                                                                                    |
| `watermark`            | boolean          |  否  | `false` | 是否将 Viggle 水印嵌入视频，与其他模式的用法一致。                                                                               |
| `priority`             | integer          |  否  | `1000`  | 与 H3 模式共用的准入队列优先级。必须使用服务端支持的档位（当前为 `1000` 或 `0`），否则返回 `400 INVALID_REQUEST`："unsupported priority"。通常无需设置。  |

本模式没有单独的 `source` 参数，由 `driving_video_url`、`character_image_url` 或 `character_image_urls` 选择。进入角色动画模式后，至少需要一张角色图片。若三个字段都不提供，则根据其他字段进入[文本生成视频](/zh/v1/api-reference/videos/create-from-text)等模式。

### 驱动视频与角色图片

* **驱动视频**（`driving_video_url`）：可省略，仅凭角色图片也能生成。若提供，长度必须为 5–10 秒（含边界），比本 API 其他视频输入的 0.5–600 秒范围更窄；分辨率至少为 64×64，宽高均为偶数。无法下载 URL 时返回 `400 INVALID_REQUEST`："failed to fetch driving\_video\_url"。
* **角色图片**（`character_image_url` / `character_image_urls`）：至少一张。\*\* 无驱动视频时最多 4 张；有驱动视频时仅允许 1 张\*\*。超限会返回 `400 INVALID_REQUEST`："at most 4 character images are allowed"，或 "only one character\_image\_url is allowed when driving\_video\_url is provided"。两个图片字段不能同时使用，否则返回 "supply only one of character\_image\_url or character\_image\_urls"。

所有驱动视频和角色图片 URL 都必须使用 `https://` 或 `gs://`。其他协议（例如 `http://`）会返回 `400 INVALID_REQUEST`，例如 "each character\_image\_url must be a gs\:// or https\:// URI"；驱动视频字段会返回对应的错误信息。

<a id="json-request-body" />

## JSON 请求体

只有角色动画模式支持普通 JSON 请求体（`Content-Type: application/json`），也支持原生数组。由于本模式无需上传文件，可直接使用：

```json theme={null}
{
  "driving_video_url": "https://example.test/driving.mp4",
  "character_image_urls": ["https://example.test/char1.png", "https://example.test/char2.png"],
  "prompt": "keep the same outfit and background",
  "watermark": false
}
```

请求体必须为单个 JSON 对象，包含 `driving_video_url`、`character_image_url` 或 `character_image_urls` 中的至少一个字段，并满足上方的角色图片要求。空请求体或格式错误会返回 `400 INVALID_REQUEST`："request body must be a JSON object"；缺少这三个字段时会返回 "JSON animation requests require character images"。

JSON 对象的键不能重复，因此 `character_image_url` 只能保存一个字符串。需要多张图片时，使用 `character_image_urls` 原生数组。

## 响应参数

返回 `200 OK`，表示请求已受理，并非最终结果。

| 字段           | 类型             | 始终返回 | 说明                    |
| ------------ | -------------- | :--: | --------------------- |
| `id`         | string         |   是  | 以 `anim_` 开头的视频公开 ID。 |
| `status`     | string         |   是  | 受理时固定为 `queued`。      |
| `progress`   | integer 或 null |   是  | 受理时固定为 `null`。        |
| `created_at` | string         |   是  | ISO 8601 创建时间，精确到秒。   |

```json theme={null}
{
  "id": "anim_7c1e4b",
  "status": "queued",
  "progress": null,
  "created_at": "2026-09-09T09:12:03Z"
}
```

创建响应不包含 `video_url`、`completed_at` 或 `error`。处理过程中或完成后的完整结构见[获取视频](/zh/v1/api-reference/videos/get)。角色动画的查询响应没有 `seed` 字段，该字段仅适用于 H3。

## 计费

每次受理的请求固定收取 **11 积分（\$0.11）**，创建时扣费，与实际输出时长无关。实际时长需在服务端测量驱动视频后才能确定，而积分预留更早发生，因此每次请求按最大可能输出（约 10 秒）统一计费。`watermark` 不影响价格。详见[计费与保留期限](/zh/v1/pricing)。

## 示例

<CodeGroup>
  ```bash cURL（multipart，驱动视频与单张角色图片） theme={null}
  curl https://apis.viggle.ai/v1/videos \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -F driving_video_url=https://example.test/driving.mp4 \
    -F character_image_url=https://example.test/char1.png
  ```

  ```bash cURL（multipart，仅角色图片） theme={null}
  curl https://apis.viggle.ai/v1/videos \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -F prompt="keep the same outfit and background" \
    -F character_image_url=https://example.test/char1.png \
    -F character_image_url=https://example.test/char2.png
  ```

  ```bash cURL（JSON 请求体） theme={null}
  curl https://apis.viggle.ai/v1/videos \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "driving_video_url": "https://example.test/driving.mp4",
          "character_image_urls": ["https://example.test/char1.png"]
        }'
  ```

  ```python Python theme={null}
  import os, requests
  response = requests.post(
      "https://apis.viggle.ai/v1/videos",
      headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}", "Content-Type": "application/json"},
      json={
          "driving_video_url": "https://example.test/driving.mp4",
          "character_image_urls": ["https://example.test/char1.png"],
      },
  )
  response.raise_for_status()
  video = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/v1/videos", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VIGGLE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      driving_video_url: "https://example.test/driving.mp4",
      character_image_urls: ["https://example.test/char1.png"],
    }),
  });
  const video = await response.json();
  ```
</CodeGroup>

## 常见错误

| 错误                                                                                                       | 原因                                                                           |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `400 INVALID_REQUEST` — "character images are required"                                                  | 未提供 `character_image_url` 或 `character_image_urls`。                          |
| `400 INVALID_REQUEST` — "supply only one of character\_image\_url or character\_image\_urls"             | 同时提供了两个图片字段。                                                                 |
| `400 INVALID_REQUEST` — "at most 4 character images are allowed"                                         | 角色图片总数超过 4 张。                                                                |
| `400 INVALID_REQUEST` — "only one character\_image\_url is allowed when driving\_video\_url is provided" | 有驱动视频时提供了多张角色图片。                                                             |
| `400 INVALID_REQUEST` — "each character\_image\_url must be a gs\:// or https\:// URI"                   | 图片 URL 协议不是 `https://` 或 `gs://`；使用复数字段时错误信息中的字段名相应为 `character_image_urls`。 |
| `400 INVALID_REQUEST` — "driving\_video\_url must be a gs\:// or https\:// URI"                          | 驱动视频 URL 使用了不支持的协议。                                                          |
| `400 INVALID_REQUEST` — "driving\_video\_url must be a single URL"                                       | 重复提供了驱动视频 URL。                                                               |
| `400 INVALID_REQUEST` — "failed to fetch driving\_video\_url"                                            | 无法下载驱动视频。                                                                    |
| `400 INVALID_REQUEST` — "driving\_video\_url duration must be between 5 and 10 seconds (inclusive)"      | 驱动视频长度不在 5–10 秒范围内。                                                          |
| `400 INVALID_REQUEST` — "driving\_video\_url/character\_image\_url cannot be combined with quality"      | 角色动画字段与 `quality` 等 H3 字段混用。                                                 |
| `400 INVALID_REQUEST` — "unsupported priority"                                                           | `priority` 不属于服务端支持的档位。                                                      |

## 下一步

使用返回的 `id` 调用[获取视频](/zh/v1/api-reference/videos/get)，轮询生成结果。

<CardGroup cols={2}>
  <Card title="从文本生成视频" icon="text" href="/zh/v1/api-reference/videos/create-from-text">
    仅凭提示词生成，无需帧图片或参考素材。
  </Card>

  <Card title="从参考视频或图片生成视频" icon="clapperboard" href="/zh/v1/api-reference/videos/create-from-reference-video">
    使用 H3 延续参考视频或最多 4 张图片的主体或风格。
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/openapi.yaml POST /v1/videos
openapi: 3.0.3
info:
  title: Viggle API
  description: 使用 AI 生成角色动画视频。
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: 生产服务器
security:
  - bearerAuth: []
tags:
  - name: Renders
    description: 准备输入、创建渲染、观察进度并获取结果。
  - name: Credits
    description: 查询当前调用者可用的积分余额。
  - name: Characters
    description: 创建、列出、查询和删除可复用角色。type 决定是否同时提取 3D vsplat，就绪后通过导出接口获取下载链接。
  - name: Motions
    description: 创建、列出、查询和删除可复用动作，也可从官方模板导入。type 决定是否提取或生成 3D 动画，就绪后通过导出接口获取下载链接。
  - name: Videos
    description: 生成 MiniMax H3 视频（vid_）或角色动画视频（anim_），并统一查询调用者的 H3、角色动画及角色动作渲染（render_）结果。
paths:
  /v1/videos:
    post:
      tags:
        - Videos
      summary: 生成视频
      description: 支持文本、首帧、首尾帧、参考素材及 Viggle-Animate 角色动画五种模式，由输入字段决定。
      operationId: createVideo
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/SourceChannel'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateVideoForm'
      responses:
        '200':
          description: 请求成功。
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/V1Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: 可选的调用者自定义关联 ID，最长 128 字符。服务会在响应头返回实际使用的值，便于追踪和支持排查。
      schema:
        type: string
        minLength: 1
        maxLength: 128
    SourceChannel:
      name: X-Viggle-Source
      in: header
      required: false
      description: 可选来源标签，最长 128 字符，用于识别 SDK、集成、产品入口或内部工作流。
      schema:
        type: string
        minLength: 1
        maxLength: 128
  schemas:
    CreateVideoForm:
      description: >-
        POST /v1/videos 根据输入选择模式：无帧、参考或角色动画字段时为文本生成；只有首帧时为首帧生成；首尾帧同时提供时为首尾帧生成；任一
        reference_video/reference_video_url/reference_image/reference_image_url
        字段选择参考素材模式；driving_video_url 或角色图片字段选择独立的 Viggle-Animate。默认使用
        multipart，角色动画也支持 JSON。每个帧位置的文件与 URL 互斥，尾帧必须配合首帧，否则返回 400
        INVALID_REQUEST。参考模式没有单独的 source/mode 参数，遗漏所有参考字段会回退到文本生成。参考视频的文件与 URL
        合计最多 1 个，参考图片合计最多 4 张；超限或与首尾帧混用均返回 400 INVALID_REQUEST。参考视频长 0.5–600
        秒，至少 64×64，宽高均为偶数，duration_s
        控制生成视频而非参考视频长度。角色动画至少需要一张角色图片，character_image_url 与 character_image_urls
        互斥；无驱动视频最多 4 张，有驱动视频仅 1 张。驱动视频可选，只能一个 URL，时长为 5–10 秒（含边界），至少
        64×64，宽高为偶数。角色动画不能与 quality 或帧、参考字段混用，不支持
        duration_s、resolution、aspect_ratio、seed，prompt 可选。H3 按 duration_s
        向上取整后每秒 1 积分（\$0.01）计费，low/high 同价，分辨率、宽高比及图片或视频条件不影响价格。角色动画每次固定 11
        积分。H3 视频自带原生音频，无需额外开关。完整字段及错误信息见各模式的接口正文。
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
          description: H3 模式必填且非空；Viggle-Animate 模式可选，不强制非空。
          example: A paper airplane gliding through a sunlit office
        quality:
          type: string
          enum:
            - low
            - high
          description: H3 模式必填：low 生成更快，high 保真度更高，两者均为 \$0.01/秒。不可与角色动画字段混用。
          example: low
        first_frame_image:
          type: string
          format: binary
          description: 直接上传的首帧图片，与 `first_frame_image_url` 二选一。
        first_frame_image_url:
          type: string
          format: uri
          description: 可公开访问的首帧图片 URL。服务会下载并重新托管，与 `first_frame_image` 二选一。
        last_frame_image:
          type: string
          format: binary
          description: 直接上传的尾帧图片，与 `last_frame_image_url` 二选一。必须同时提供首帧。
        last_frame_image_url:
          type: string
          format: uri
          description: 可公开访问的尾帧图片 URL。服务会下载并重新托管，与 `last_frame_image` 二选一。必须同时提供首帧。
        reference_video:
          type: array
          maxItems: 1
          items:
            type: string
            format: binary
          description: >-
            直接上传的参考视频。为兼容未来扩展，字段声明为可重复，但当前与 `reference_video_url` 合计最多 1
            个视频。提供参考图片时可省略。
        reference_video_url:
          type: array
          maxItems: 1
          items:
            type: string
            format: uri
          description: 可公开访问的参考视频 URL，服务会下载并重新托管。字段声明为可重复，但当前与文件形式合计最多 1 个视频。
        reference_image:
          type: array
          maxItems: 4
          items:
            type: string
            format: binary
          description: 直接上传的参考图片，可重复，也可与 `reference_image_url` 混用，两种形式合计最多 4 张。
        reference_image_url:
          type: array
          maxItems: 4
          items:
            type: string
            format: uri
          description: 可公开访问的参考图片 URL，服务会下载并重新托管。可重复，也可与文件形式混用，合计最多 4 张。
        driving_video_url:
          type: string
          format: uri
          description: >-
            驱动视频 URL，其动作将应用到角色图片。支持 `https://` 或内部 `gs://`，仅可提供一个值。视频须为 5–10
            秒（含边界）、至少 64×64 像素，且宽高均为偶数。
        character_image_url:
          type: array
          items:
            type: string
            format: uri
          description: 角色参考图片 URL，可重复。与 `character_image_urls` 互斥。
        character_image_urls:
          type: array
          items:
            type: string
            format: uri
          description: >-
            与 `character_image_url` 等效，但将多个值放入一个字段。multipart 中使用 JSON 字符串数组，JSON
            请求体中使用原生数组。与 `character_image_url` 互斥。
        priority:
          type: integer
          description: >-
            与 H3 模式共用的准入队列优先级。必须使用服务端支持的档位（当前为 `1000` 或 `0`），否则返回 `400
            INVALID_REQUEST`："unsupported priority"。通常无需设置。
          default: 1000
        duration_s:
          type: number
          minimum: 3
          maximum: 15
          default: 5
          description: 生成时长，单位为秒，范围 3–15。计费时向上取整。
        resolution:
          type: string
          enum:
            - 480p
            - 768p
            - 1080p
          default: 768p
          description: '`480p`、`768p` 或 `1080p`，不影响价格。'
        aspect_ratio:
          type: string
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
            - '4:3'
            - '3:4'
            - '21:9'
          default: '16:9'
          description: '`16:9`、`9:16`、`1:1`、`4:3`、`3:4` 或 `21:9`，不影响价格。'
        seed:
          type: integer
          minimum: 0
          description: 大于或等于 0；省略时使用随机种子。
        watermark:
          type: boolean
          default: false
          description: 是否将 Viggle 水印嵌入视频，与其他模式的用法一致。
    VideoCreateResponse:
      description: >-
        POST /v1/videos 五种模式共用的受理响应，只表示排队成功，并非最终结果。轮询 GET
        /v1/videos/{video_id}，直至 ready 后读取 video_url；也可通过视频列表查看任务状态。
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - progress
        - created_at
      properties:
        id:
          type: string
          description: 视频公开 ID：H3 为 vid_ 前缀，角色动画为 anim_ 前缀。
          minLength: 1
        status:
          description: 受理时固定为 `queued`。
          allOf:
            - $ref: '#/components/schemas/ResourceStatus'
        progress:
          type: integer
          description: 受理时固定为 `null`。
          nullable: true
          minimum: 0
          maximum: 100
        created_at:
          type: string
          description: ISO 8601 创建时间，精确到秒。
          nullable: true
          format: date-time
    ResourceStatus:
      description: 异步资源共用的公开生命周期，枚举值与 RenderStatus 相同。
      type: string
      enum:
        - queued
        - processing
        - ready
        - failed
        - cancelled
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: 草稿流程的顶层错误，包含稳定错误码、说明、重试建议、关联 ID 和错误详情。
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - retryable
        - request_id
        - details
        - remediation
      properties:
        code:
          description: 恢复方法
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: 供人阅读的描述，不要解析其文本做逻辑判断。
        retryable:
          type: boolean
          description: 重试相同请求是否可能成功。
        request_id:
          type: string
          description: 用于关联 Viggle 日志与支持排查。仅当异步工作进程无法恢复原请求 ID 时为 `null`。
        details:
          type: object
          description: 补充结构化信息，可能为空。
          additionalProperties: true
        remediation:
          description: >-
            `{action, retry_after_ms}`，表示下一步操作。除非建议定时重试，否则 `retry_after_ms` 为
            `null`。
          allOf:
            - $ref: '#/components/schemas/ErrorRemediation'
    ErrorCode:
      description: 草稿渲染流程的错误码集合。资源操作将相应错误映射为 ResourceError 说明的小写下划线形式。
      type: string
      enum:
        - UNAUTHENTICATED
        - INVALID_CREDENTIAL
        - FORBIDDEN
        - INVALID_REQUEST
        - INVALID_CHARACTER
        - INVALID_MOTION
        - UNSUPPORTED_MEDIA
        - CONTENT_POLICY_VIOLATION
        - UPLOAD_REQUIRED
        - UPLOAD_MISMATCH
        - UPLOAD_EXPIRED
        - DRAFT_NOT_FOUND
        - DRAFT_ALREADY_CONSUMED
        - RENDER_NOT_FOUND
        - RENDER_NOT_CANCELLABLE
        - CHARACTER_NOT_FOUND
        - MOTION_NOT_FOUND
        - MOTION_NOT_READY
        - MOTION_TEMPLATE_NOT_FOUND
        - AVATAR_NOT_FOUND
        - ANIMATION_NOT_FOUND
        - EXTRACTION_UNAVAILABLE
        - EXTRACTION_FAILED
        - IDEMPOTENCY_KEY_REUSED
        - INSUFFICIENT_CREDITS
        - RATE_LIMITED
        - SERVICE_BUSY
        - INTERNAL_ERROR
    ErrorRemediation:
      type: object
      additionalProperties: false
      required:
        - action
        - retry_after_ms
      properties:
        action:
          type: string
          description: 建议的下一步操作，供程序或人工读取，例如稍后重试、重新上传或修正输入。
        retry_after_ms:
          type: integer
          description: 建议重试等待的毫秒数；无需定时重试时为 null。
          nullable: true
          format: int64
          minimum: 0
  headers:
    RequestId:
      description: 用于支持排查和追踪的稳定请求 ID。
      schema:
        type: string
  responses:
    BadRequest:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    V1Unauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: 请求失败，详情见错误响应。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: 请求失败，详情见错误响应。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

````