Skip to main content
POST
创建动作
发送 application/json,即可通过提示词生成 3D 骨骼动画。文本生成的动作始终为 type: glb,因为它没有可供 2D 渲染使用的视频。 本模式与从视频创建动作共用 POST /v1/motions,但请求内容类型和字段不同。它替代已移除的 POST /v1/animations/generate
每次请求固定 10 积分(1 积分 = $0.01),与 duration_seconds 无关。从视频创建动作的 GLB 提取则按秒计费,详见计费与保留期限

请求参数

使用 application/json

响应参数

返回 200 OK 和排队中的 Motion 对象。

示例

下一步

使用获取动作轮询,直到 status=ready,再调用导出 3D 动作获取 mixamometahuman GLB。

快速入门:文本生成动作

查看完整的创建、轮询和导出流程。

授权

Authorization
string
header
必填

服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

请求头

X-Request-Id
string

可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。

Required string length: 1 - 128
X-Viggle-Source
string

可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。

Required string length: 1 - 128

请求体

motion_video 与 motion_video_url 必须二选一。type 决定输出,提取参数仅适用于 glb/all。暂存路径、输出位置、提取模板、角色 PKL、关节配置和追踪蒙版由服务管理。

motion_video
file

直接上传的驱动视频,提取其中可见的身体动作用于复用。与 motion_video_url 二选一。

motion_video_url
string<uri>

可公开访问的驱动视频 HTTP(S) URL,替代文件上传,并在开始接收素材时保持可访问。

name
string
默认值:""

render/all 的可选名称。仅 glb 的动作当前返回空名称。

type
enum<string>
默认值:render

render 创建 2D 动作(不收费);glb 提取 3D 动画(源视频时长向上取整后按 5 积分/秒);all 同时创建并合并费用。

可用选项:
render,
glb,
all
enable_smoothing
boolean
默认值:false

是否平滑提取的关节动作,减少帧间抖动,也可能略微弱化突然的动作。

target_fps
number
默认值:30

提取和 GLB 时间轴的目标帧率,必须大于 0。省略时使用 30 FPS。

必填范围: x > 0
task_id
string

type=glb 的调用者自定义幂等 ID。同一任务重试使用稳定且唯一的值;type=all 使用新建动作 ID 作为配套提取任务的键。

Minimum string length: 1

响应

请求成功。

角色和动作共用的资源结构。列表中的 progress 为 null,顶层 error 当前始终为 null,失败请检查 status。角色 type 为 render、vsplat、all,动作为 render、glb、all,旧资源默认报告 render。vsplat/glb 仅包含提取状态,下载链接通过角色或动作的 /export 获取。未请求提取时对应字段为 null。all 需等 2D 与 3D 均就绪才为 ready;任一失败则顶层 failed,子对象状态可用于定位。

id
string
必填

素材公开 ID。角色通常以 char_ 开头,动作通常以 mot_ 开头。

Minimum string length: 1
status
enum<string>
必填

素材整体生命周期。所需能力就绪后才能用于渲染或导出。

可用选项:
queued,
processing,
ready,
failed,
cancelled
name
string
必填

创建时提供或导入时生成的显示名称;不支持名称的流程可能返回空字符串。

progress
integer | null
必填

详情中尽可能提供 0–100 的处理百分比,列表中或不可用时为 null。

必填范围: 0 <= x <= 100
capabilities
string[]
必填

素材具备的能力。就绪且可渲染时包含 video_render。

created_at
string | null
必填

带 UTC 偏移的 ISO 8601 时间,例如 2026-07-31T09:15:22+00:00。

completed_at
string | null
必填

所有请求处理进入终态时的 ISO 8601 时间,带 UTC 偏移;处理中为 null。

error
object | null
必填

保留的顶层错误详情,目前始终为 null。通过 status 判断失败,并在适用时检查提取子对象。

type
enum<string>
默认值:render
必填

创建时请求的输出。render 为可渲染的 2D 素材,vsplat/glb 为 3D 输出,all 同时请求两种支持的输出。

可用选项:
render,
vsplat,
glb,
all
vsplat
object | null
必填

角色 vsplat 提取状态。动作及 type=render 的角色为 null。这里只返回状态,不回显 model_precision 等创建参数。

glb
object | null
必填

动作 3D 动画提取或生成状态。角色及 type=render 的动作为 null。