> ## 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 API V1

> 使用 Viggle API V1 创建可控的角色动作视频。

<Note>
  **V1 是当前版本的 API。** 新项目请使用 V1。已有的 `/api/*` 接入可按照[迁移指南](/zh/v1/production/migrate-from-legacy)升级。
</Note>

Viggle API 以可复用素材、异步操作和输出文件为核心。角色（Character）和动作（Motion）只需创建一次，即可用于多个渲染任务（Render）。Render 代表一次操作，其 MP4 和可选的 Alpha 视频是该操作的输出文件。

```mermaid theme={null}
graph LR
  A["角色素材"] --> D["渲染操作"]
  B["动作素材"] --> D
  C["直接输入图片或视频"] --> D
  D --> E["视频输出文件"]
```

## 创建第一个渲染任务

<Steps>
  <Step title="获取 API 密钥" icon="key">
    在 [Viggle 控制台](https://portal.viggle.ai/keys)创建 API 密钥。
  </Step>

  <Step title="创建渲染任务" icon="film">
    向 `POST /v1/renders` 上传图片和动作视频。
  </Step>

  <Step title="等待结果" icon="clock">
    轮询 `GET /v1/videos/{render_id}`，直到 `status` 为 `ready`，然后使用 `video_url`。
  </Step>
</Steps>

<Columns cols={2}>
  <Card title="快速入门：视频重混" icon="play" href="/zh/v1/guides/quickstart-mix">
    将角色图片和动作视频合成为成品视频。
  </Card>

  <Card title="快速入门：3D 动作" icon="activity" href="/zh/v1/guides/quickstart-mocap">
    从动作视频提取可下载的 3D（GLB）动画。
  </Card>
</Columns>

## 选择工作流程

<Columns cols={2}>
  <Card title="快速入门：参考素材生成视频" icon="clapperboard" href="/zh/v1/guides/quickstart-reference-to-video">
    结合参考视频或图片与文本提示词生成视频。
  </Card>

  <Card title="立即渲染" icon="zap" href="/zh/v1/guides/quickstart-mix">
    在一次请求中上传图片和动作视频，适合首次体验或一次性任务。
  </Card>

  <Card title="复用素材" icon="refresh-cw" href="/zh/v1/guides/reuse-assets">
    创建角色和动作后，在后续渲染请求中引用其 ID。
  </Card>
</Columns>

## 核心概念

| 概念                    | 含义                                                                 |
| --------------------- | ------------------------------------------------------------------ |
| 角色（Character）         | 从图片创建的可复用角色，ID 以 `char_` 开头。`type=vsplat`/`all` 还会提取 3D 高斯泼溅模型。    |
| 动作（Motion）            | 从视频提取或从文本生成的可复用驱动动作，ID 以 `mot_` 开头。`type=glb`/`all` 还会提取或生成 3D 动画。 |
| 渲染任务（Render）          | 一次异步视频生成任务，ID 以 `render_` 开头。                                      |
| 动作模板（Motion Template） | Viggle 官方动作，可通过模板 ID 直接用于渲染，也可导入为自己的动作资源。                          |

## 下一步

<Columns cols={3}>
  <Card title="身份验证" icon="lock" href="/zh/v1/authentication">安全地发送 API 密钥。</Card>
  <Card title="API 参考" icon="code" href="/zh/v1/api-reference/overview">浏览全部 V1 资源。</Card>
  <Card title="生产接入指南" icon="server" href="/zh/v1/production/async-jobs">处理异步任务和失败。</Card>
</Columns>