> ## 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` 指定的官方模板复制为当前调用者拥有的动作素材。
按源模板时长收取 1 积分/秒，最低 1 积分（1 积分 = \$0.01）。详见[计费与保留期限](/zh/v1/pricing#import-motion)。
## 请求参数
使用 JSON 请求体。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --------------- | ------ | :-: | ---------------------------- | ----------------------------------------------------------------------- |
| `template_id` | string | 二选一 | — | 要复制的 Viggle 官方动作模板 ID，新接入推荐使用。与 `template_uuid` 二选一。 |
| `template_uuid` | string | 二选一 | — | `template_id` 的向后兼容别名，不要同时传入两个字段。 |
| `name` | string | 否 | `Imported: ` 加模板 ID 的前 8 个字符 | 导入动作的可选名称。省略时根据模板 ID 自动生成。 |
| `model` | string | 否 | `V3_Preview` | 关联的渲染模型：`V3_Preview` 或 `V4_BaseSG`。兼容旧别名 `V4_Preview`，其等同于 `V4_BaseSG`。 |
新接入请使用 `template_id`，未知字段会被忽略。
## 响应参数
返回 `200 OK`。此响应只有 `id` 和 `status` 提供有效信息；`name` 和 `created_at` 请通过[获取动作](/zh/v1/api-reference/motions/get)读取。完整 Motion 字段定义见[创建动作](/zh/v1/api-reference/motions/create)。
```json theme={null}
{"id":"mot_550e8400-e29b-41d4-a716-446655440000","status":"queued","name":"","progress":0,"capabilities":[],"created_at":null,"completed_at":null,"error":null,"type":"render","vsplat":null,"glb":null}
```
## 示例
```go Go theme={null}
payload := strings.NewReader(`{"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"}`)
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/motions/import", payload)
req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type", "application/json")
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/import", {method:"POST", headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`,"Content-Type":"application/json"}, body:JSON.stringify({template_id:"YOUR_TEMPLATE_ID",name:"Campaign dance"})});
const motion = await response.json();
```
```python Python theme={null}
import os, requests
response = requests.post("https://apis.viggle.ai/v1/motions/import", headers={"Authorization":f"Bearer {os.environ['VIGGLE_API_KEY']}"}, json={"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"})
response.raise_for_status(); motion = response.json()
```
```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions/import" -H "Authorization: Bearer $VIGGLE_API_KEY" -H "Content-Type: application/json" -d '{"template_id":"YOUR_TEMPLATE_ID","name":"Campaign dance"}'
```
## OpenAPI
````yaml zh/openapi.yaml POST /v1/motions/import
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/import:
post:
tags:
- Motions
summary: 导入动作
description: 从 Viggle 官方动作模板创建可复用动作。
operationId: importMotion
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImportMotionRequest'
responses:
'200':
description: 请求成功。
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
'400':
$ref: '#/components/responses/ResourceBadRequest'
'401':
$ref: '#/components/responses/ResourceUnauthorized'
'402':
$ref: '#/components/responses/ResourcePaymentRequired'
'404':
$ref: '#/components/responses/ResourceNotFound'
'500':
$ref: '#/components/responses/ResourceInternalServerError'
'503':
$ref: '#/components/responses/ResourceServiceUnavailable'
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:
ImportMotionRequest:
description: template_uuid 是 template_id 的兼容别名，二选一，未知属性忽略。按模板时长 1 积分/秒计费，最低 1 积分。
type: object
anyOf:
- required:
- template_id
- required:
- template_uuid
properties:
template_id:
type: string
description: 要复制的 Viggle 官方动作模板 ID，新接入推荐使用。与 `template_uuid` 二选一。
minLength: 1
template_uuid:
type: string
description: '`template_id` 的向后兼容别名，不要同时传入两个字段。'
minLength: 1
name:
description: 导入动作的可选名称。省略时根据模板 ID 自动生成。
type: string
model:
description: >-
关联的渲染模型：`V3_Preview` 或 `V4_BaseSG`。兼容旧别名 `V4_Preview`，其等同于
`V4_BaseSG`。
type: string
enum:
- V3_Preview
- V4_BaseSG
- V4_Preview
default: V3_Preview
Asset:
description: >-
角色和动作共用的资源结构。列表中的 progress 为 null，顶层 error 当前始终为 null，失败请检查 status。角色
type 为 render、vsplat、all，动作为 render、glb、all，旧资源默认报告 render。vsplat/glb
仅包含提取状态，下载链接通过角色或动作的 /export 获取。未请求提取时对应字段为 null。all 需等 2D 与 3D 均就绪才为
ready；任一失败则顶层 failed，子对象状态可用于定位。
type: object
additionalProperties: false
required:
- id
- status
- name
- progress
- capabilities
- created_at
- completed_at
- error
- type
- vsplat
- glb
properties:
id:
type: string
description: 素材公开 ID。角色通常以 char_ 开头，动作通常以 mot_ 开头。
minLength: 1
status:
description: 素材整体生命周期。所需能力就绪后才能用于渲染或导出。
allOf:
- $ref: '#/components/schemas/ResourceStatus'
name:
type: string
description: 创建时提供或导入时生成的显示名称；不支持名称的流程可能返回空字符串。
progress:
type: integer
description: 详情中尽可能提供 0–100 的处理百分比，列表中或不可用时为 null。
nullable: true
minimum: 0
maximum: 100
capabilities:
description: 素材具备的能力。就绪且可渲染时包含 video_render。
type: array
items:
type: string
created_at:
description: 带 UTC 偏移的 ISO 8601 时间，例如 2026-07-31T09:15:22+00:00。
type: string
nullable: true
completed_at:
type: string
description: 所有请求处理进入终态时的 ISO 8601 时间，带 UTC 偏移；处理中为 null。
nullable: true
error:
type: object
description: 保留的顶层错误详情，目前始终为 null。通过 status 判断失败，并在适用时检查提取子对象。
nullable: true
allOf:
- $ref: '#/components/schemas/ResourceError'
type:
type: string
description: 创建时请求的输出。render 为可渲染的 2D 素材，vsplat/glb 为 3D 输出，all 同时请求两种支持的输出。
enum:
- render
- vsplat
- glb
- all
default: render
vsplat:
description: >-
角色 vsplat 提取状态。动作及 type=render 的角色为 null。这里只返回状态，不回显 model_precision
等创建参数。
nullable: true
type: object
additionalProperties: false
required:
- status
- error
properties:
status:
description: 角色 vsplat 提取自身的生命周期，独立于顶层素材状态。
allOf:
- $ref: '#/components/schemas/ResourceStatus'
error:
type: object
description: vsplat 状态为 failed 时的结构化错误，否则为 null。
nullable: true
allOf:
- $ref: '#/components/schemas/ResourceError'
glb:
description: 动作 3D 动画提取或生成状态。角色及 type=render 的动作为 null。
nullable: true
type: object
additionalProperties: false
required:
- status
- skeletons
- error
properties:
status:
description: 动作 3D 提取或生成自身的生命周期，独立于顶层素材状态。
allOf:
- $ref: '#/components/schemas/ResourceStatus'
skeletons:
description: >-
可通过 GET /v1/motions/{motion_id}/export?download_type=
导出的骨架。就绪前为空；两种骨架预先一起生成，就绪后为 [mixamo, metahuman]。
type: array
items:
type: string
enum:
- mixamo
- metahuman
error:
type: object
description: 3D 动画状态为 failed 时的结构化错误，否则为 null。
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
headers:
RequestId:
description: 用于支持排查和追踪的稳定请求 ID。
schema:
type: string
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'
ResourcePaymentRequired:
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'
ResourceInternalServerError:
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 访问令牌。不要在浏览器代码中暴露项目密钥。
````