Skip to main content
GET
导出 3D 动作(用于 3D/游戏引擎)
仅适用于 type=glb/all 的动作,或通过 POST /v1/motions 的 JSON 模式从文本生成的动作。仅 render 的动作无可导出内容。本接口替代已移除的 GET /v1/animations/{animation_id}。 download_type 选择的是文件格式——glb 或 fbx——而非骨架。每次请求会一次性返回三种骨架对应该格式的链接:mixamo_url、metahuman_url、metahuman_body_url。三种骨架的两种格式都已预先生成,因此在同一个 motion_id 上切换 download_type 不会触发新任务或重新生成。GLB 可用于 Mixamo、MetaHuman 以及其他兼容 Unity 的动画流程;FBX 是同一批骨架与动作烘焙成的 FBX 文件,供需要该格式的流程(Unreal、Blender、Maya 等)使用。
选择骨架: mixamo_url 是通用的 50 关节骨架,通常需要重定向到自己的角色网格。对于 Viggle vsplat 角色,metahuman_url 是与 joint_set=full 对应的 441 关节完整骨架,metahuman_body_url 是与 joint_set=body 对应的 86 关节身体骨架。Motion 导出当前没有与 joint_set=expression 对应的独立 119 关节文件。

请求参数

响应参数

返回 200 OK。 三个骨架链接字段始终出现在响应中——不同于按骨架单独设 download_type 取值的设计,这里没有哪个字段会被有条件地省略。某个骨架尚未就绪(或不适用)时,对应字段保持 null,不会报错,也不会从响应中消失。
同一动作改用 fbx,无需重新生成——同样三个字段这次改为 FBX 链接:
省略 download_type(仅查询状态)时,三个链接字段均为 null:

示例

下载链接有效期较短,每次读取都会重新签名。需要时请再次指定 download_type 获取,不要长期缓存。
download_type 传入 glb/fbx 之外的任何值会返回 400 INVALID_REQUEST:“invalid download_type”。

下一步

文本生成的动作没有 2D 渲染素材,只能使用本导出接口。视频来源的动作若具备 video_render 能力且已就绪,可将 motion_id 用于渲染视频。

授权

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_id
string
必填

创建或列出动作时返回的公开 ID,通常以 mot_ 开头,必须属于当前调用者。

Minimum string length: 1

查询参数

download_type
enum<string>

选择预生成的文件格式并返回对应签名 URL:glb 或 fbx。该格式下的三个骨架变体(mixamo_url、metahuman_url、metahuman_body_url)会一起返回。

可用选项:
glb,
fbx

响应

请求成功。

动作 3D 提取或文本生成的下载结果。download_type 选择的是文件格式——glb 或 fbx——而非骨架;每次请求会 一次性解析该格式下三种骨架的链接(mixamo_url、metahuman_url、metahuman_body_url)。两种格式下的三种 骨架均由同一次生成流程预先产出,因此切换 download_type 不会触发新任务或等待。三个 URL 字段始终出现 在响应中——尚未就绪的骨架保持为 null,既不会报错也不会从响应中消失。下载链接短期有效,每次读取重新 签名,替代旧 AnimationResource 和已移除的 GET /v1/animations/{animation_id}。

id
string
必填

所请求的动作公开 ID。

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

queued、processing、ready 或 failed。

可用选项:
queued,
processing,
ready,
failed,
cancelled
download_type
enum<string> | null
必填

请求中选择的文件格式,下方三个骨架链接字段共用同一格式;省略时为 null。

可用选项:
glb,
fbx,
null
mixamo_url
string | null
必填

对应 download_type 格式的 Mixamo 骨架签名 URL,就绪后有值,否则为 null。无论请求了哪种格式(或未请求),本字段始终出现。

metahuman_url
string | null
必填

对应 download_type 格式的 441 关节 MetaHuman(含完整面部)骨架签名 URL,就绪后有值,否则为 null。始终出现。

metahuman_body_url
string | null
必填

对应 download_type 格式的 86 关节 MetaHuman 身体版骨架签名 URL,就绪后有值,否则为 null。始终出现。

thumbnail_url
string | null
必填

动画没有缩略图,始终为 null。

created_at
string | null
必填

ISO 8601 时间。尚未记录时可能为空字符串。

updated_at
string | null
必填

最近更新时间,ISO 8601 格式。

error
object | null
必填

失败时的结构化错误详情。