> ## 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.

# 导出 3D 动作（用于 3D／游戏引擎）

> 获取提取或生成的 3D 动画的签名下载链接。

仅适用于 `type=glb`/`all` 的动作，或通过 `POST /v1/motions` 的 JSON 模式从文本生成的动作。仅 `render` 的动作无可导出内容。本接口替代已移除的 `GET /v1/animations/{animation_id}`。

`download_type` 直接选择骨架（`mixamo` 或 `metahuman`），而非输出格式。不提供 `fbx`；两种骨架会预先生成，对同一 `motion_id` 切换骨架不会触发新任务或重新生成。导出的 GLB 可用于 **Mixamo**、**MetaHuman** 以及其他兼容 **Unity** 的动画流程。

<Note>
  **选择骨架：** `mixamo` 是通用的 50 关节骨架，适用于 Mixamo、Unity、Unreal 和多数 DCC 工具。它未绑定具体角色，需重定向到自己的角色网格才能正确播放。`metahuman` 与 Viggle vsplat 角色使用的 MetaHuman 兼容骨架一致，关节层级完全对应，可直接驱动角色，无需重定向，见[创建角色](/zh/v1/api-reference/characters/create)中的 `joint_set`。该骨架有包含完整面部及表情动画能力的 441 关节版本，以及不含面部关节的 86 关节身体版本；请匹配角色创建时的 `joint_set`。
</Note>

## 请求参数

| 参数              | 类型     |  必填 | 说明                                            |
| --------------- | ------ | :-: | --------------------------------------------- |
| `motion_id`     | string |  是  | 创建、生成、导入或列出动作时返回的完整 ID，动作须包含已请求的 3D 动画输出。     |
| `download_type` | string |  否  | 选择预生成骨架的 GLB：`mixamo` 或 `metahuman`。省略时仅查询状态。 |

## 响应参数

返回 `200 OK`。

| 字段              | 类型            | 始终返回 | 说明                                        |
| --------------- | ------------- | :--: | ----------------------------------------- |
| `id`            | string        |   是  | 所请求的动作公开 ID。                              |
| `status`        | string        |   是  | `queued`、`processing`、`ready` 或 `failed`。 |
| `download_type` | string 或 null |   是  | 请求中选择的骨架，省略时为 `null`。                     |
| `glb_url`       | string 或 null |   是  | 指定 `download_type` 且对应骨架就绪时有值。            |
| `thumbnail_url` | null          |   是  | 动画没有缩略图，始终为 `null`。                       |
| `created_at`    | string 或 null |   是  | ISO 8601 时间。尚未记录时可能为空字符串。                 |
| `updated_at`    | string 或 null |   是  | 最近更新时间，ISO 8601 格式。                       |
| `error`         | object 或 null |   是  | 失败时的结构化错误详情。                              |

```json theme={null}
{
  "id": "mot_456def",
  "status": "ready",
  "download_type": "mixamo",
  "glb_url": "https://assets.viggle.ai/results/animation_mixamo.glb",
  "thumbnail_url": null,
  "created_at": "2026-07-21T10:00:00+00:00",
  "updated_at": "2026-07-21T10:01:00+00:00",
  "error": null
}
```

同一动作改用 `metahuman`，无需重新生成：

```json theme={null}
{
  "id": "mot_456def",
  "status": "ready",
  "download_type": "metahuman",
  "glb_url": "https://assets.viggle.ai/results/animation_metahuman.glb",
  "thumbnail_url": null,
  "created_at": "2026-07-21T10:00:00+00:00",
  "updated_at": "2026-07-21T10:01:00+00:00",
  "error": null
}
```

## 示例

<CodeGroup>
  ```go Go theme={null}
  req,_:=http.NewRequest("GET","https://apis.viggle.ai/v1/motions/mot_456def/export?download_type=mixamo",nil); req.Header.Set("Authorization","Bearer "+os.Getenv("VIGGLE_API_KEY")); resp,err:=http.DefaultClient.Do(req); if err!=nil {panic(err)}; defer resp.Body.Close()
  ```

  ```javascript JavaScript theme={null}
  const response=await fetch("https://apis.viggle.ai/v1/motions/mot_456def/export?download_type=mixamo",{headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`}}); const exported=await response.json();
  ```

  ```python Python theme={null}
  import os, requests
  response=requests.get("https://apis.viggle.ai/v1/motions/mot_456def/export",params={"download_type":"mixamo"},headers={"Authorization":f"Bearer {os.environ['VIGGLE_API_KEY']}"}); response.raise_for_status(); exported=response.json()
  ```

  ```bash cURL theme={null}
  curl "https://apis.viggle.ai/v1/motions/mot_456def/export?download_type=mixamo" -H "Authorization: Bearer $VIGGLE_API_KEY"
  ```
</CodeGroup>

<Tip>
  下载链接有效期较短，每次读取都会重新签名。需要时请再次指定 `download_type` 获取，不要长期缓存。
</Tip>

## 下一步

文本生成的动作没有 2D 渲染素材，只能使用本导出接口。视频来源的动作若具备 `video_render` 能力且已就绪，可将 `motion_id` 用于[渲染视频](/zh/v1/api-reference/renders/create)。


## OpenAPI

````yaml zh/openapi.yaml GET /v1/motions/{motion_id}/export
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/motions/{motion_id}/export:
    parameters:
      - $ref: '#/components/parameters/MotionId'
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/SourceChannel'
    get:
      tags:
        - Motions
      summary: 导出 3D 动作（用于 3D／游戏引擎）
      description: 获取提取或生成的 3D 动画的签名下载链接。
      operationId: exportMotion
      parameters:
        - name: download_type
          in: query
          required: false
          description: 选择预生成骨架的签名 GLB：mixamo 为 Mixamo 兼容骨架，metahuman 为 MetaHuman 兼容骨架。
          schema:
            type: string
            enum:
              - mixamo
              - metahuman
      responses:
        '200':
          description: 请求成功。
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionExport'
        '400':
          $ref: '#/components/responses/ResourceBadRequest'
        '401':
          $ref: '#/components/responses/ResourceUnauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ResourceConflict'
        '500':
          $ref: '#/components/responses/ResourceInternalServerError'
        '502':
          $ref: '#/components/responses/ResourceBadGateway'
        '503':
          $ref: '#/components/responses/ResourceServiceUnavailable'
components:
  parameters:
    MotionId:
      name: motion_id
      in: path
      required: true
      description: 创建或列出动作时返回的公开 ID，通常以 mot_ 开头，必须属于当前调用者。
      schema:
        type: string
        minLength: 1
      example: mot_7d2e9f1a3c5b4e8d9f0a1b2c3d4e5f60
    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
  schemas:
    MotionExport:
      description: >-
        动作 3D 提取或文本生成的下载结果。指定 download_type=mixamo 或 metahuman 后返回相应
        glb_url。两种骨架预先生成，切换不会创建新任务。不支持 fbx。下载链接短期有效，每次读取重新签名，替代旧
        AnimationResource 和已移除的 GET /v1/animations/{animation_id}。
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - download_type
        - glb_url
        - thumbnail_url
        - created_at
        - updated_at
        - error
      properties:
        id:
          type: string
          description: 所请求的动作公开 ID。
          minLength: 1
        status:
          description: '`queued`、`processing`、`ready` 或 `failed`。'
          allOf:
            - $ref: '#/components/schemas/ResourceStatus'
        download_type:
          description: 请求中选择的骨架，省略时为 `null`。
          type: string
          nullable: true
          enum:
            - mixamo
            - metahuman
            - null
        glb_url:
          type: string
          description: 指定 `download_type` 且对应骨架就绪时有值。
          nullable: true
        thumbnail_url:
          description: 动画没有缩略图，始终为 `null`。
          type: string
          nullable: true
        created_at:
          description: ISO 8601 时间。尚未记录时可能为空字符串。
          type: string
          nullable: true
        updated_at:
          type: string
          description: 最近更新时间，ISO 8601 格式。
          nullable: true
        error:
          type: object
          description: 失败时的结构化错误详情。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ResourceError'
    ResourceStatus:
      description: 异步资源共用的公开生命周期，枚举值与 RenderStatus 相同。
      type: string
      enum:
        - queued
        - processing
        - ready
        - failed
        - cancelled
    ResourceError:
      description: >-
        异步资源附带的错误。code 为稳定的小写下划线字符串，故意不限制为枚举，工作进程可能新增值；无公开映射时使用
        processing_failed。已发布值包括
        worker_stopped、motion_model_mismatch、image_required、motion_video_required、unsupported_video_format、video_too_long、video_too_large、video_resolution_too_high、video_unreadable、invalid_background_mode、video_dimensions_must_be_even、result_expired、video_inaccessible、no_humans_detected、all_workers_busy、task_failed、unexpected_error、processing_failed。
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          description: 稳定的小写下划线异步错误码。集合可扩展，客户端应容忍新值。
          minLength: 1
        message:
          type: string
          description: 供人阅读的异步处理失败说明。
        request_id:
          type: string
          description: 工作进程或原始请求的关联 ID，不可用时为 null。
          nullable: true
    ResourceErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: 同步资源操作失败的顶层错误对象。
          allOf:
            - $ref: '#/components/schemas/ResourceHttpError'
    ResourceHttpError:
      description: >-
        同步资源请求的错误封装。错误码由 API 服务中的固定映射生成，无公开映射的失败使用 processing_failed。资源的异步 error
        对象采用 ResourceError 中更广泛、可扩展的错误码集合。
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          description: 同步资源请求的固定小写下划线错误码，用于程序化处理。
          enum:
            - authentication_required
            - invalid_api_key
            - insufficient_credits
            - invalid_request
            - motion_not_ready
            - character_not_found
            - motion_not_found
            - not_found
            - id_already_exists
            - rate_limited
            - service_unavailable
            - task_failed
            - internal_error
            - processing_failed
        message:
          type: string
          description: 供人阅读的同步请求失败说明。
        request_id:
          description: 同步失败时始终为 null，请通过 X-Request-Id 响应头关联请求。
          type: string
          nullable: true
  responses:
    ResourceBadRequest:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceUnauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceNotFound:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceConflict:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceInternalServerError:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceBadGateway:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceServiceUnavailable:
      description: 请求失败，详情见错误响应。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

````