> ## 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 动作模板库，获取可导入的 template_id。

浏览 Viggle 官方发布的动作模板库——与 Viggle App 和 Discord 机器人展示的模板相同。用于在调用[导入动作](/zh/v1/api-reference/motions/import)之前找到 `template_id`。

<Note>
  本接口原样透传上游模板库的响应。响应体的具体字段不属于 V1 的版本化契约——将其视为浏览辅助工具，读取每一项的 `id` 字段，作为 `template_id` 传给导入动作接口。这与其他所有承诺固定响应结构的 V1 接口不同。
</Note>

## 查询参数

全部为可选参数。

| 参数                        | 类型      | 说明                                                                  |
| ------------------------- | ------- | ------------------------------------------------------------------- |
| `searchKeyword`           | string  | 对模板库的自由文本搜索。                                                        |
| `tagID`                   | string  | 按单个标签过滤，可用值见[获取动作模板标签](/zh/v1/api-reference/motions/template-tags)。 |
| `multiType`               | integer | 模板中的角色数量：`0` 单人，`1` 多人。                                             |
| `multiplePersonTagIdType` | integer | 多人标签过滤：`multiType=1` 且未指定 `tagID` 时，`1` 应用默认多人标签，`0` 关闭该过滤。         |
| `type`                    | integer | 模板发布的平台：`0` Web（默认）、`1` Discord、`2` App。                            |
| `page`                    | integer | 页码，从 1 开始。                                                          |
| `pageSize`                | integer | 每页结果数。                                                              |

```bash theme={null}
curl "https://apis.viggle.ai/v1/motion-templates?searchKeyword=dance&page=1&pageSize=20" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 响应

`200 OK`，原样返回模板库响应。每一项至少包含 `id` 字段——即用作 `template_id` 的值：

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "data": [
    { "id": "tpl_1a2b3c", "command": "wave" },
    { "id": "tpl_4d5e6f", "command": "sit" }
  ]
}
```

<Card title="导入动作" icon="download" href="/zh/v1/api-reference/motions/import">
  将模板的 `id` 复制为账户下的可复用动作素材。
</Card>


## OpenAPI

````yaml zh/openapi.yaml GET /v1/motion-templates
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/motion-templates:
    get:
      tags:
        - Motions
      summary: 浏览官方动作模板库
      description: >-
        原样透传官方 Viggle 模板库的响应。响应体的具体结构不属于版本化契约——读取每一项的 `id` 字段，将其作为 `template_id`
        传给[导入动作](/zh/v1/api-reference/motions/import)。用 `GET
        /v1/motion-template-tags` 解析 `tagID` 取值。
      operationId: listMotionTemplates
      parameters:
        - name: multiType
          in: query
          description: 模板的角色数量。`0` 为单人，`1` 为多人。
          required: false
          schema:
            type: integer
        - name: multiplePersonTagIdType
          in: query
          description: 多人标签过滤。`multiType=1` 且未指定 `tagID` 时，`1` 应用默认多人标签，`0` 关闭该过滤。
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: 页码，从 1 开始。
          required: false
          schema:
            type: integer
            minimum: 1
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
        - name: searchKeyword
          in: query
          required: false
          schema:
            type: string
        - name: tagID
          in: query
          description: 用于过滤的标签，取自 `GET /v1/motion-template-tags`。
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: 平台：`0` Web（默认）、`1` Discord、`2` App。
          required: false
          schema:
            type: integer
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/SourceChannel'
      responses:
        '200':
          description: 原样透传上游模板库响应，结构不作约束。
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/V1Unauthorized'
        '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
  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'
    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'
  schemas:
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

````