> ## 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 动作。
发送 `application/json`，即可通过提示词生成 3D 骨骼动画。文本生成的动作始终为 `type: glb`，因为它没有可供 2D 渲染使用的视频。
本模式与[从视频创建动作](/zh/v1/api-reference/motions/create)共用 `POST /v1/motions`，但请求内容类型和字段不同。它替代已移除的 `POST /v1/animations/generate`。
每次请求固定 10 积分（1 积分 = \$0.01），与 `duration_seconds` 无关。[从视频创建动作](/zh/v1/api-reference/motions/create)的 GLB 提取则按秒计费，详见[计费与保留期限](/zh/v1/pricing)。
## 请求参数
使用 `application/json`。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------------------ | ---------------- | :-: | ------ | ----------------------------------------------------------------------- |
| `text` | string（1–400 字符） | 是 | — | 动作的自然语言描述。可写明动作、方向、节奏及相关身体部位，使结果更明确。 |
| `duration_seconds` | number | 否 | `5` | 动画时长，单位为秒，按 30 FPS 四舍五入到最近帧。超出 `[3, 60]` 返回 `400`，不会自动截断。不影响固定 10 积分价格。 |
| `guidance_scale` | number | 否 | `5` | 提示词对生成的引导强度，范围 `0`–`30`，越界返回 `400`。 |
| `smooth` | boolean | 否 | `true` | 是否平滑动画，减少相邻帧关节突变。 |
| `name` | string | 否 | `""` | 详情和列表显示的名称，不影响生成。 |
| `task_id` | string | 否 | — | 调用者自定义幂等 ID，用于安全重试。同一生成任务使用相同值，不同任务使用新值。 |
## 响应参数
返回 `200 OK` 和排队中的 Motion 对象。
| 字段 | 类型 | 始终返回 | 说明 |
| ----------------------------- | -------------- | :--: | ---------------------------------------------------------------------- |
| `id` | string | 是 | 以 `mot_` 开头的公开 ID，请原样保存。 |
| `status` | string | 是 | 通常为 `queued`；终态为 `ready`/`failed`。 |
| `name` | string | 是 | 传入的名称，或空字符串。 |
| `progress` | integer 或 null | 是 | 可用时为 0–100 的进度。 |
| `capabilities` | string\[] | 是 | 文本生成动作没有 2D 渲染能力，因此为空。 |
| `created_at` / `completed_at` | string 或 null | 是 | ISO 8601 时间。 |
| `error` | object 或 null | 是 | 失败时的结构化错误详情。 |
| `type` | string | 是 | 固定为 `glb`。 |
| `glb` | object 或 null | 是 | 生成中及完成后包含 `{status, skeletons, error}`。就绪时同时提供 `mixamo` 和 `metahuman`。 |
| `vsplat` | null | 是 | 动作始终为 `null`。 |
```json theme={null}
{
"id": "mot_550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"name": "Cartwheel",
"progress": 0,
"capabilities": [],
"created_at": "2026-07-21T10:00:00+00:00",
"completed_at": null,
"error": null,
"type": "glb",
"vsplat": null,
"glb": {
"status": "queued",
"skeletons": [],
"error": null
}
}
```
## 示例
```go Go theme={null}
payload := strings.NewReader(`{"text":"a person doing a cartwheel","duration_seconds":5,"guidance_scale":7.5,"smooth":true,"name":"Cartwheel","task_id":"motion-cartwheel-001"}`)
req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/motions", 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", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.VIGGLE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
text: "a person doing a cartwheel",
duration_seconds: 5,
guidance_scale: 7.5,
smooth: true,
name: "Cartwheel",
task_id: "motion-cartwheel-001",
}),
});
const motion = await response.json();
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://apis.viggle.ai/v1/motions",
headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
json={
"text": "a person doing a cartwheel",
"duration_seconds": 5,
"guidance_scale": 7.5,
"smooth": True,
"name": "Cartwheel",
"task_id": "motion-cartwheel-001",
},
)
response.raise_for_status()
motion = response.json()
```
```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions" \
-H "Authorization: Bearer $VIGGLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"a person doing a cartwheel","duration_seconds":5,"guidance_scale":7.5,"smooth":true,"name":"Cartwheel","task_id":"motion-cartwheel-001"}'
```
## 下一步
使用[获取动作](/zh/v1/api-reference/motions/get)轮询，直到 `status=ready`，再调用[导出 3D 动作](/zh/v1/api-reference/motions/export)获取 `mixamo` 或 `metahuman` GLB。
查看完整的创建、轮询和导出流程。
## OpenAPI
````yaml zh/openapi.yaml POST /v1/motions
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:
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
post:
tags:
- Motions
summary: 创建动作
description: 使用 multipart 从视频创建动作，或使用 JSON 从文本生成 3D 动作。
operationId: createMotion
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateMotionForm'
application/json:
schema:
$ref: '#/components/schemas/CreateMotionRequest'
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'
'409':
$ref: '#/components/responses/ResourceConflict'
'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:
CreateMotionForm:
description: >-
motion_video 与 motion_video_url 必须二选一。type 决定输出，提取参数仅适用于
glb/all。暂存路径、输出位置、提取模板、角色 PKL、关节配置和追踪蒙版由服务管理。
type: object
properties:
motion_video:
type: string
format: binary
description: 直接上传的驱动视频，提取其中可见的身体动作用于复用。与 `motion_video_url` 二选一。
motion_video_url:
type: string
format: uri
description: 可公开访问的驱动视频 HTTP(S) URL，替代文件上传，并在开始接收素材时保持可访问。
name:
description: '`render`/`all` 的可选名称。仅 `glb` 的动作当前返回空名称。'
type: string
default: ''
type:
type: string
description: >-
`render` 创建 2D 动作（不收费）；`glb` 提取 3D 动画（源视频时长向上取整后按 5 积分/秒）；`all`
同时创建并合并费用。
enum:
- render
- glb
- all
default: render
enable_smoothing:
type: boolean
description: 是否平滑提取的关节动作，减少帧间抖动，也可能略微弱化突然的动作。
default: false
target_fps:
description: 提取和 GLB 时间轴的目标帧率，必须大于 `0`。省略时使用 30 FPS。
type: number
minimum: 0
exclusiveMinimum: true
default: 30
task_id:
description: >-
`type=glb` 的调用者自定义幂等 ID。同一任务重试使用稳定且唯一的值；`type=all` 使用新建动作 ID
作为配套提取任务的键。
type: string
minLength: 1
CreateMotionRequest:
description: >-
POST /v1/motions 的 JSON 文本生成动作模式，输出固定为 type: glb。替代旧
GenerateMotionRequest 和 POST /v1/animations/generate，每次固定 10 积分，与
duration_seconds 无关。
type: object
additionalProperties: false
required:
- text
properties:
text:
type: string
description: 动作的自然语言描述。可写明动作、方向、节奏及相关身体部位，使结果更明确。
minLength: 1
maxLength: 400
duration_seconds:
description: >-
动画时长，单位为秒，按 30 FPS 四舍五入到最近帧。超出 `[3, 60]` 返回 `400`，不会自动截断。不影响固定 10
积分价格。
type: number
minimum: 3
maximum: 60
default: 5
guidance_scale:
description: 提示词对生成的引导强度，范围 `0`–`30`，越界返回 `400`。
type: number
minimum: 0
maximum: 30
default: 5
smooth:
type: boolean
description: 是否平滑动画，减少相邻帧关节突变。
default: true
name:
type: string
description: 详情和列表显示的名称，不影响生成。
default: ''
task_id:
type: string
description: 调用者自定义幂等 ID，用于安全重试。同一生成任务使用相同值，不同任务使用新值。
minLength: 1
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'
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'
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 访问令牌。不要在浏览器代码中暴露项目密钥。
````