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

# 动作

> 创建、导入、获取、列出、删除和导出可复用动作。

动作（Motion）是从视频提取的驱动动作，或从提示词生成的 3D 动画，不代表背景场景。具备渲染能力的动作可通过 `mot_...` ID 作为 `motion_id` 用于渲染。

所有接口均需 `Authorization: Bearer YOUR_API_KEY`。逐字段说明见[视频创建](/zh/v1/api-reference/motions/create)、[文本创建](/zh/v1/api-reference/motions/create-from-text)、[导入](/zh/v1/api-reference/motions/import)、[列表](/zh/v1/api-reference/motions/list)、[获取](/zh/v1/api-reference/motions/get)、[删除](/zh/v1/api-reference/motions/delete)、[导出](/zh/v1/api-reference/motions/export)。

## 从视频创建动作

`POST /v1/motions`

请求形式由 `Content-Type` 决定。`multipart/form-data` 从驱动视频创建动作：

| 字段                 | 类型     |  必填 | 默认值      | 说明                                                  |
| ------------------ | ------ | :-: | -------- | --------------------------------------------------- |
| `motion_video`     | file   | 二选一 | —        | 直接上传的驱动视频。                                          |
| `motion_video_url` | string | 二选一 | —        | 驱动视频的公开 URL。                                        |
| `name`             | string |  否  | `""`     | 显示名称。                                               |
| `type`             | string |  否  | `render` | `render` 免费预处理；`glb` 按源视频时长向上取整后 5 积分/秒；`all` 合并两者。 |

`glb`/`all` 还接受 `enable_smoothing`、`target_fps` 和 `task_id`。缩略图由内部从源视频生成，详见[从视频创建动作](/zh/v1/api-reference/motions/create)。

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "motion_video=@dance.mp4" \
  -F "name=Dance loop"
```

## 从文本创建动作

同一接口通过 `application/json` 从提示词生成动作，固定为 `type: glb`，替代已移除的 `POST /v1/animations/generate`。每次固定 10 积分，与 `duration_seconds` 无关，不按视频提取的每秒价格收费。

| 字段                 | 类型      |  必填 | 默认值    | 说明                              |
| ------------------ | ------- | :-: | ------ | ------------------------------- |
| `text`             | string  |  是  | —      | 1–400 字符的动作提示词。                 |
| `duration_seconds` | number  |  否  | `5`    | 范围 `[3, 60]`，按 30 FPS 四舍五入至最近帧。 |
| `guidance_scale`   | number  |  否  | `5`    | 无分类器引导强度，范围 `[0, 30]`。          |
| `smooth`           | boolean |  否  | `true` | 是否平滑动作。                         |
| `name`             | string  |  否  | `""`   | 显示名称。                           |
| `task_id`          | string  |  否  | —      | 客户端提供的幂等键。                      |

```bash 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}'
```

## 导入动作模板

`POST /v1/motions/import`

使用 JSON 从 Viggle 模板导入动作，按模板时长 1 积分/秒计费，最低 1 积分。

| 字段              | 类型     |  必填 | 默认值                        | 说明                                                           |
| --------------- | ------ | :-: | -------------------------- | ------------------------------------------------------------ |
| `template_id`   | string | 二选一 | —                          | Viggle 模板 ID，推荐字段。                                           |
| `template_uuid` | string | 二选一 | —                          | 向后兼容的别名。                                                     |
| `name`          | string |  否  | `Imported: ` 加模板 ID 前 8 字符 | 导入动作名称。                                                      |
| `model`         | string |  否  | `V3_Preview`               | `V3_Preview` 或 `V4_BaseSG`；旧别名 `V4_Preview` 等同于 `V4_BaseSG`。 |

```bash 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"}'
```

<Note>
  两个模板字段同时存在时，`template_id` 优先。新接入只发送 `template_id`。
</Note>

## 获取动作

`GET /v1/motions/{motion_id}`

```bash theme={null}
curl "https://apis.viggle.ai/v1/motions/mot_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 列出动作

`GET /v1/motions`

返回当前账户最近创建的有效动作，从新到旧，最多 100 条，无游标。

```bash theme={null}
curl "https://apis.viggle.ai/v1/motions" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 删除动作

`DELETE /v1/motions/{motion_id}`

```bash theme={null}
curl -X DELETE "https://apis.viggle.ai/v1/motions/mot_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## 导出 3D 动画

`GET /v1/motions/{motion_id}/export`

仅适用于 `glb`/`all` 或文本生成动作。`download_type` 直接选择 `mixamo` 或 `metahuman` 骨架，两者预先生成，切换无需重新生成，不提供 `fbx`。`mixamo` 是通用 50 关节骨架，需重定向到自己的角色；`metahuman` 与 Viggle vsplat 角色一一对应，包含 441 关节完整面部版或 86 关节身体版，需匹配[创建角色](/zh/v1/api-reference/characters/create)的 `joint_set`，无需重定向。详见[导出 3D 动作](/zh/v1/api-reference/motions/export)。

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

## 动作响应字段

Motion 结构包含 `id`、`status`、`name`、`progress`、`capabilities`、`type`、`glb`、`created_at`、`completed_at` 和 `error`。请求 3D 提取或生成时，`glb` 为 `{status, skeletons, error}`，否则为 `null`；`skeletons` 就绪前为空，就绪后为 `[mixamo, metahuman]`。ID 例如 `mot_550e8400-e29b-41d4-a716-446655440000`，请原样保存。

## 接口响应规则

| 接口                                   | 成功状态  | 响应                        | 参数                          |
| ------------------------------------ | ----- | ------------------------- | --------------------------- |
| `POST /v1/motions`（multipart）        | `200` | Motion 对象                 | 一个视频来源，可选 3D 参数由 `type` 决定。 |
| `POST /v1/motions`（JSON）             | `200` | `type: glb` 的 Motion      | 必填 `text`，其余生成参数可选。         |
| `POST /v1/motions/import`            | `200` | Motion 对象                 | 模板 ID 二选一，名称可选。             |
| `GET /v1/motions`                    | `200` | `{ "data": [Motion] }`    | 无。                          |
| `GET /v1/motions/{motion_id}`        | `200` | Motion 对象                 | 必填 `motion_id`。             |
| `DELETE /v1/motions/{motion_id}`     | `200` | `{ "status": "deleted" }` | 必填 `motion_id`。             |
| `GET /v1/motions/{motion_id}/export` | `200` | MotionExport 对象           | 必填 ID，可选 `download_type`。   |