# LoopRouter 文档 — 全量文档

> LoopRouter AI API 网关官方文档 — 视频生成、真人素材与 Doubao Seedream 图像接口

---

URL: https://docs.looprouter.com/index.md

# LoopRouter 文档中心

> LoopRouter — 企业级 AI 视频生成 API 网关，提供与火山引擎完全兼容的 Doubao Seedance 视频生成与素材库接口

LoopRouter 是一个面向企业与开发者的 AI API 网关，当前聚焦 **Doubao Seedance 视频生成**能力：统一的 API Key、统一的计费与日志、与火山引擎方舟（Ark）**完全兼容**的接口路径，让你无需改动请求结构即可从官方 SDK / 现有代码平滑迁移。

<div style={{ display: 'flex', alignItems: 'center', gap: '12px', flexWrap: 'wrap', margin: '16px 0' }}>
  <button
    type="button"
    data-ai-read-button
    style={{
      display: 'inline-flex',
      alignItems: 'center',
      gap: '8px',
      padding: '10px 20px',
      borderRadius: '12px',
      border: 'none',
      cursor: 'pointer',
      fontSize: '14px',
      fontWeight: 600,
      color: '#fff',
      backgroundColor: '#E37756',
    }}
  >
    🤖 让 AI 阅读
  </button>
  <span style={{ fontSize: '13px', opacity: 0.75 }}>
    一键复制推荐提示词，粘贴给 ChatGPT / Claude 即可开始接入与测试 → 详见 <a href="/ai-usage">AI 集成指南</a>
  </span>
</div>

## 服务地址

| 用途 | 地址 |
| --- | --- |
| API 接入点 | `https://api.looprouter.com` |
| 用户控制台 | `https://console.looprouter.com` |
| 文档站 | `https://docs.looprouter.com` |

## 核心能力

<CardGroup cols={2}>
  <Card title="Seedance 2.0 视频生成" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    文生视频、首尾帧图生视频、多模态参考生视频，接口路径与火山引擎原厂完全一致
  </Card>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/seedance2/overview">
    模型清单、技术规格、分辨率与宽高比、计费方式一页看懂
  </Card>
  <Card title="素材库" icon="images" href="/asset-management/asset-library">
    上传并管理参考素材，获取 asset ID 用于角色一致性生成
  </Card>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    真人人像素材需先通过活体认证，全流程 API 化，无需人工介入
  </Card>
  <Card title="AI 集成指南" icon="robot" href="/ai-usage">
    把文档直接交给 ChatGPT / Claude：llms.txt 索引、每页 Markdown 版本与推荐提示词
  </Card>
</CardGroup>

## 为什么选择 LoopRouter

<CardGroup cols={2}>
  <Card title="原厂兼容" icon="plug">
    创建 / 查询任务接口与火山引擎方舟同路径、同参数、同响应结构，迁移零成本
  </Card>
  <Card title="透明计费" icon="receipt">
    提交预扣、完成结算，被拒绝的请求不扣费，日志中心可逐条核对
  </Card>
  <Card title="稳定限流" icon="gauge-high">
    渠道级 RPM 智能调度与排队重试，高并发下任务不丢失
  </Card>
  <Card title="任务式异步" icon="clock">
    标准任务生命周期（queued → running → succeeded），轮询即可拿到成片
  </Card>
</CardGroup>

## 快速开始

<Steps>
  <Step title="注册并获取 API Key">
    前往 [控制台](https://console.looprouter.com) 注册账号，在「令牌」页创建一个 `sk-` 开头的 API Key。
  </Step>
  <Step title="发起第一个视频任务">
    按照 [快速开始](/getting-started) 中的 cURL 示例提交一个文生视频任务。
  </Step>
  <Step title="轮询并下载成片">
    用返回的任务 ID 查询状态，`succeeded` 后从 `content.video_url` 下载视频。
  </Step>
</Steps>

<Note>
遇到问题？请通过控制台内的工单或联系方式与我们沟通，我们通常会在工作时间内快速响应。
</Note>

---

URL: https://docs.looprouter.com/getting-started.md

# 快速开始

> 三步完成接入：创建 API Key → 提交视频任务 → 轮询获取成片

本页带你用最短路径跑通 LoopRouter 的 Seedance 2.0 视频生成。

## 第一步：创建 API Key

<Steps>
  <Step title="注册账号">
    打开 [console.looprouter.com](https://console.looprouter.com) 完成注册与登录。
  </Step>
  <Step title="创建令牌">
    进入「令牌」页面，新建一个令牌，得到形如 `sk-xxxx` 的 API Key。请妥善保管，不要提交到代码仓库。
  </Step>
  <Step title="确认额度">
    在「钱包」页面确认账户余额充足。视频生成为预扣费模式，余额不足会直接返回错误。
  </Step>
</Steps>

## 第二步：提交视频生成任务

<CodeGroup>

```bash cURL
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "海边日落，无人机航拍视角缓缓推进，金色阳光洒在海面上"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'
```

```python Python
import requests

resp = requests.post(
    "https://api.looprouter.com/api/v3/contents/generations/tasks",
    headers={
        "Authorization": "Bearer sk-你的APIKey",
        "Accept-Encoding": "identity",
    },
    json={
        "model": "doubao-seedance-2-0-260128",
        "content": [
            {"type": "text", "text": "海边日落，无人机航拍视角缓缓推进，金色阳光洒在海面上"}
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
)
print(resp.json())  # {"id": "cgt-xxxx"}
```

</CodeGroup>

创建接口只返回任务 ID，**不会**直接返回视频：

```json
{"id": "cgt-20260721-xxxx"}
```

## 第三步：轮询任务并下载视频

```bash cURL
curl "https://api.looprouter.com/api/v3/contents/generations/tasks/cgt-20260721-xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

任务状态依次经历 `queued → running → succeeded / failed`。成功后响应中的 `content.video_url` 即为成片下载地址。

<Warning>
`video_url` 是带签名的临时链接，**约 2 小时后过期**，拿到后请尽快转存到自己的存储。下载视频时不要携带 `Authorization` 请求头。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="完整参数说明" icon="book" href="/api-capabilities/seedance2/video-generation">
    首尾帧、多模态参考、音频等全部生成模式与参数
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/create-video-task">
    在文档内直接填参数发起真实请求
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/user-groups.md

# 分组说明：VIP 组与补贴组

> VIP 组与补贴组的区别：计费折扣、可用分辨率档位与画质稳定性差异，以及如何选择和切换分组

LoopRouter 目前提供两个用户分组：**VIP 组（优等组）** 与 **补贴组**。分组决定了三件事：**计费折扣**、**可用的分辨率档位**，以及**画质与稳定性**。创建 API 令牌时选择分组，即可按需组合使用。

## 两个分组一览

| | VIP 组（优等组） | 补贴组 |
| --- | --- | --- |
| **计费折扣** | **商务对接获取** | **商务对接获取** |
| **可用分辨率** | `480p` / `720p` / `1080p` / `4k` 全档位 | `720p` / `1080p` |
| **画质与稳定性** | 画质上限更高（独享 `4k`）、更稳定 | 标准 |
| **适合场景** | 精品产出与「打样 → 生产 → 精品」全档位工作流 | 成本敏感的批量跑量、打样验证 |

<Info>
新注册账号默认处于 **VIP 组**。两个分组均对所有用户开放，无需申请。
</Info>

## VIP 组（优等组）

VIP 组的计费折扣以**商务对接约定**为准，定位是「更好、更全、更稳」：

- **全分辨率档位**：是唯一开放 `480p` 与 `4k` 的分组。`480p` 单价最低，适合大批量打样、快速验证提示词；`4k` 用于精品成片输出。配合 `720p`/`1080p`，可以覆盖「低成本试错 → 主力生产 → 精品重出」的完整工作流。
- **画质上限更高、生成更稳定**：独享的 `4k` 档位可产出更高画质的精品成片；生成线路更稳定，任务成功率与整体体验更优。

## 补贴组

补贴组按 **商务对接的折扣** 计费，定位是「更低成本覆盖主力档位」：

- **价格更低**：`720p`/`1080p` 任务以商务对接约定的优惠折扣计费，长期跑量下成本优势明显。
- **主力档位齐全**：开放 `720p` 与 `1080p` 两档，满足绝大多数日常生成与投流素材需求；不提供 `480p` 与 `4k`。

<Tip>
一个常见的组合用法：用 **补贴组** 的令牌跑 `720p`/`1080p` 的日常批量任务压低成本，用 **VIP 组** 的令牌处理 `480p` 快速打样与 `4k` 精品输出。
</Tip>

## 如何选择与切换分组

<Steps>
  <Step title="创建令牌时选择分组">
    在 [控制台 → 令牌](https://console.looprouter.com/keys) 新建令牌时，可在「令牌分组」中选择 VIP 组或补贴组。该令牌发起的所有请求都按所选分组计费与调度。
  </Step>
  <Step title="按用途持有多个令牌">
    同一账号可以同时创建两个分组的令牌，业务侧按场景切换 API Key 即可，无需改动其他参数。
  </Step>
  <Step title="留空则跟随账号默认分组">
    令牌分组留空时跟随账号所在分组（新用户默认 VIP 组）。想固定某个令牌的行为，建议显式选择分组。
  </Step>
</Steps>

## 常见问题

<AccordionGroup>
  <Accordion title="传了分组不支持的分辨率会怎样？">
    创建任务时会直接返回 **400**，错误信息会列出当前分组实际可用的档位（如补贴组传 `4k` 会提示 `resolution 仅支持 720P、1080P`），该请求**不扣费**。切换到 VIP 组令牌即可使用全部档位。
  </Accordion>
  <Accordion title="两个分组生成的画质有区别吗？">
    同一模型、同一分辨率且其他参数相同时，两个分组的成片画质**基本一致**。VIP 组的「画质更优」主要体现在档位覆盖上——独享 `4k` 精品档与 `480p` 打样档，可产出补贴组无法生成的更高分辨率成片；同时生成线路更稳定。补贴组的差异在可用档位与价格，而非同参数下的画质。
  </Accordion>
  <Accordion title="分组折扣和视频输入折扣可以叠加吗？">
    可以。分组倍率与[视频输入优惠](/faq/billing-and-balance)相互独立，包含参考视频的请求会在分组折扣的基础上再应用视频输入的优惠倍率，无需额外传参。
  </Accordion>
  <Accordion title="各分组的具体单价在哪里看？">
    以 [控制台「模型广场」](https://console.looprouter.com) 展示为准，切换分组即可查看对应折后价；每笔任务的实际扣费可在「日志中心」逐条核对。
  </Accordion>
  <Accordion title="以后还会有其他分组吗？">
    分组体系是平台的长期能力，后续可能根据业务推出新的分组或调整权益，届时会在[最新公告](/news/overview)中同步。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="分辨率与时长" icon="expand" href="/faq/resolution-ratio-duration">
    各档位参数与限制
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    预扣结算与折扣规则
  </Card>
  <Card title="并发与限流" icon="gauge-high" href="/faq/concurrency-and-ratelimit">
    429 应对与重试实践
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/ai-usage.md

# AI 集成指南

> 让 ChatGPT、Claude 等 AI 助手直接读取本文档站：llms.txt 索引、每页 Markdown 版本与推荐提示词

本文档站为 AI 助手（ChatGPT、Claude、Cursor 等）做了专门适配。你可以把文档直接「喂」给 AI，让它替你完成接入、写代码、跑测试。

## AI 友好入口

| 入口 | 地址 | 说明 |
| --- | --- | --- |
| 文档索引 | [`/llms.txt`](https://docs.looprouter.com/llms.txt) | 全站页面清单，AI 从这里发现所有子页面 |
| 全量文档 | [`/llms-full.txt`](https://docs.looprouter.com/llms-full.txt) | 所有页面正文合并为单个纯文本文件 |
| 单页 Markdown | 任意页面 URL 后加 `.md` | 例：[`/api-capabilities/seedance2/overview.md`](https://docs.looprouter.com/api-capabilities/seedance2/overview.md) |
| OpenAPI 规范 | [`/openapi.yaml`](https://docs.looprouter.com/openapi.yaml) | 视频任务接口的完整请求 / 响应定义 |

<Tip>
每个文档页面右上角都有「复制页面」按钮：一键把当前页以 Markdown 格式复制进剪贴板，或直接在 ChatGPT / Claude 中打开提问。
</Tip>

## 推荐提示词

把下面的提示词连同你的需求一起发给 AI 助手：

```text 给 AI 的提示词
请阅读 https://docs.looprouter.com/llms.txt 获取 LoopRouter 文档站的全部页面清单。
每个页面的 URL 后加 .md 即可获得该页的 Markdown 原文（例如
https://docs.looprouter.com/getting-started.md）；完整 API 定义见
https://docs.looprouter.com/openapi.yaml。

LoopRouter 是与火山引擎方舟（Ark）完全兼容的 Doubao Seedance 视频生成 API 网关：
- API 接入点：https://api.looprouter.com
- 鉴权方式：请求头 Authorization: Bearer <API Key>（sk- 开头）
- 创建任务：POST /api/v3/contents/generations/tasks
- 查询任务：GET /api/v3/contents/generations/tasks/{id}

请先通读文档，再按照文档中的参数说明和示例完成我的需求。
```

常见用法示例：

<CardGroup cols={2}>
  <Card title="按文档接入" icon="code">
    "按照这个文档站的说明，用 Python 写一个提交文生视频任务并轮询结果的脚本。"
  </Card>
  <Card title="按文档测试" icon="vial">
    "按照这个文档站测试视频生成 API：覆盖文生视频、首尾帧、参考图三种模式，输出测试报告。"
  </Card>
  <Card title="排查报错" icon="bug">
    "我的请求返回了这个错误（贴上报错），对照文档告诉我参数哪里不对。"
  </Card>
  <Card title="迁移代码" icon="arrows-turn-right">
    "我现在直接调用火山引擎方舟，对照文档把 base URL 和鉴权改成 LoopRouter。"
  </Card>
</CardGroup>

<Note>
AI 给出的代码和结论请以文档原文为准；涉及计费的操作（如批量提交任务）建议先用最小分辨率、最短时长验证。
</Note>

---

URL: https://docs.looprouter.com/asset-management/asset-library.md

# 素材库 API

> 上传并管理参考素材，获取 asset ID，实现角色一致性视频生成

出于防深度伪造要求，Seedance 2.0 **不允许把明星人脸图片直接放进生成请求**。想让视频里的角色保持一致（尤其是真人形象），需要先把图片放进素材库、拿到素材 ID，再在生成请求中以 `asset://素材ID` 引用。

素材库接口采用与火山引擎方舟一致的 **Action 风格**：所有操作都是同一个 URL 上的 POST 请求，通过查询参数 `Action` 区分。

## 鉴权方式

素材管理与真人认证接口支持以下两种鉴权方式。两种方式使用同一份账号素材数据，并受对应 API Key 的额度、状态、有效期和访问策略约束。

### API Key（Bearer）

```
POST https://api.looprouter.com/api/v3/assets?Action=<操作名>&Version=2024-01-01
Authorization: Bearer sk-...
Content-Type: application/json
```

<Tip>
素材库与视频生成可以使用**同一个** LoopRouter API Key，无需单独申请素材库密钥。素材归属于你的账号，其他用户无法查询或引用。
</Tip>

### 火山官方 AK/SK（HMAC-SHA256）

也可以使用 API Key 所绑定的 `Access Key ID（AK）` 和 `Secret Access Key（SK）`，按照火山官方 `HMAC-SHA256` 方式签名。已有火山客户端只需把 Endpoint 换成 `https://api.looprouter.com`，并替换为 LoopRouter API Key 页面生成的 AK/SK；Action、Version、请求体和响应解析均保持不变。

火山签名请求使用根路径 `/`，Service 为 `ark`，Region 推荐 `cn-beijing`。下面示例使用[火山官方 Go SDK](https://github.com/volcengine/volc-sdk-golang)为 `CreateAssetGroup` 请求签名：

```go
package main

import (
  "bytes"
  "io"
  "net/http"
  "os"

  "github.com/volcengine/volc-sdk-golang/base"
)

func main() {
  body := []byte(`{"Name":"我的虚拟主角","GroupType":"AIGC"}`)
  req, err := http.NewRequest(
    http.MethodPost,
    "https://api.looprouter.com/?Action=CreateAssetGroup&Version=2024-01-01",
    bytes.NewReader(body),
  )
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/json")

  credentials := base.Credentials{
    AccessKeyID:     os.Getenv("LOOPROUTER_AK"),
    SecretAccessKey: os.Getenv("LOOPROUTER_SK"),
    Region:          "cn-beijing",
    Service:         "ark",
  }
  req = credentials.Sign(req)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  io.Copy(os.Stdout, resp.Body)
}
```

<Note>
AK/SK 方式支持官方 JSON / 公网 URL 素材请求。本地文件 `multipart/form-data` 上传是 LoopRouter 扩展能力，请继续使用 API Key（Bearer）认证。视频生成接口也继续使用 API Key；AK/SK 仅用于本模块的素材管理与真人认证 Action。
</Note>

## 素材类型与处理方式

| 素材类型 | 处理方式 |
| --- | --- |
| 动漫 / 风格化角色、物品、场景 | 可直接用公网 URL 作参考图，无需素材库 |
| AI 生成的虚拟人像 | 上传到普通素材组（`GroupType: AIGC`）即可引用 |
| **真实人脸照片** | 必须先完成 [真人认证](/asset-management/real-person)，上传到认证产生的 `LivenessFace` 素材组 |

## 接口一览

| Action | 用途 |
| --- | --- |
| `CreateAssetGroup` | 创建虚拟形象素材组（GroupType 仅支持 `AIGC`） |
| `ListAssetGroups` | 列出自己的素材组（含真人认证产生的组），支持过滤 / 排序 / 分页 |
| `GetAssetGroup` | 查询单个素材组 |
| `UpdateAssetGroup` | 重命名素材组或修改描述（Description 上限 300 字） |
| `DeleteAssetGroup` | 删除素材组 |
| `CreateAsset` | 注册素材（上传素材）：公网媒体 URL（JSON）或本地文件（multipart）上传，支持图片 / 视频 / 音频，异步处理 |
| `ListAssets` | 列出素材，可按组 / 状态 / 名称过滤，支持排序与分页 |
| `GetAsset` | 查询单个素材（会同步最新处理状态） |
| `UpdateAsset` | 重命名素材 |
| `DeleteAsset` | 删除素材 |
| `CreateVisualValidateSession` | 发起真人认证（见 [真人认证接口](/asset-management/real-person)） |
| `GetVisualValidateResult` | 查询真人认证结果 |

响应统一为方舟风格信封：

```json
{
  "ResponseMetadata": {
    "RequestId": "...",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { "Id": "asset-20260709190143-ntwhb" }
}
```

出错时 `ResponseMetadata` 内会包含 `Error: {Code, Message}`，并伴随对应的 HTTP 状态码。

## 完整流程

<Steps>
  <Step title="创建素材组">

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "我的虚拟主角", "Description": "短剧项目角色A", "GroupType": "AIGC"}'

# => {"ResponseMetadata": {...}, "Result": {"Id": "group-20260709185838-dcnvd"}}
```

  </Step>
  <Step title="注册素材（上传素材）">

素材注册支持两种上传方式：**公网媒体 URL**（JSON）或**本地媒体文件**（`multipart/form-data`）。以下示例使用 API Key；公网 URL 方式也可以改用上文的火山官方 AK/SK 签名，本地文件方式仅支持 API Key。

素材可以是**图片 / 视频 / 音频**：用 `AssetType` 字段指定为 `Image` / `Video` / `Audio`（大小写不敏感），不传时默认为 `Image`。下方示例以图片为例；注册视频 / 音频时显式带上 `AssetType`（JSON 方式加字段 `"AssetType": "Video"`，本地文件方式加表单字段 `-F "AssetType=Video"`）。上传的文件类型需与 `AssetType` 匹配（`Image` → `image/*`、`Video` → `video/*`、`Audio` → `audio/*`），否则会被拒绝。

**方式一：公网媒体 URL（JSON）**

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260709185838-dcnvd",
    "Name": "角色A-正面全身",
    "URL": "https://example.com/character-a.png"
  }'

# => {"ResponseMetadata": {...}, "Result": {"Id": "asset-20260709190143-ntwhb"}}
```

**方式二：本地文件上传（multipart/form-data）**

无需自建公网 URL，直接把本地文件作为 `file` 字段上传即可（`GroupId` / `Name` / `AssetType` 用表单字段传递）：

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -F "GroupId=group-20260709185838-dcnvd" \
  -F "Name=角色A-正面全身" \
  -F "file=@/path/to/character-a.jpg;type=image/jpeg"

# => {"ResponseMetadata": {...}, "Result": {"Id": "asset-20260709190143-ntwhb"}}
```

**注册视频 / 音频素材**：与上面完全一致，只需带上 `AssetType`（此处以视频为例，音频把值换成 `Audio` 即可）。

```bash
# URL 方式（JSON）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260709185838-dcnvd",
    "Name": "参考视频-镜头A",
    "AssetType": "Video",
    "URL": "https://example.com/clip-a.mp4"
  }'

# 本地文件方式（multipart/form-data）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -F "GroupId=group-20260709185838-dcnvd" \
  -F "Name=参考视频-镜头A" \
  -F "AssetType=Video" \
  -F "file=@/path/to/clip-a.mp4;type=video/mp4"

# => {"ResponseMetadata": {...}, "Result": {"Id": "asset-20260709190312-vd9kq"}}
```

两种方式返回的信封完全一致，后续轮询状态也相同；**URL 方式**要求公网可访问。素材约束按类型区分：

- **图片（`Image`）**：格式 jpeg/png/webp/bmp/tiff/gif/heic/heif，宽高比 (0.4, 2.5)，边长 (300, 6000)px，单文件小于 30MB。
- **视频（`Video`）/ 音频（`Audio`）**：不同 Seedance 模型支持的输入音视频**时长上限不同**，请以对应模型规格为准；建议上传前记录时长，便于区分哪些素材可用于目标模型。

<Note>
本地文件上传会由平台先把文件暂存到对象存储再注册，因此需要平台已开启对象存储；**URL 方式不受此限制**。真人组（`LivenessFace`）与虚拟组（`AIGC`）都支持这两种注册方式。
</Note>

  </Step>
  <Step title="轮询素材状态至 Active">

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id": "asset-20260709190143-ntwhb"}'

# => "Result": {"Id": "asset-20260709190143-ntwhb", "Status": "Active", "GroupId": "group-20260709185838-dcnvd", ...}
```

素材注册为异步流程，通常十几秒内完成。建议每 3 秒轮询一次，`Status` 变为 `Active` 后即可使用；`Failed` 需检查图片后重新上传（`Error.Code` / `Error.Message` 字段给出原因）。

  </Step>
  <Step title="在视频生成中引用">

```bash
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图片1中的角色在樱花树下回头微笑，镜头缓慢环绕"},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
    ],
    "resolution": "720p",
    "duration": 5
  }'
```

  </Step>
</Steps>

<Warning>
提示词中请用「图片1」「图片2」（按 `content` 数组顺序）指代素材，**不要**把 `asset-` 开头的素材 ID 写进提示词文本。
</Warning>

<Warning>
素材 ID 长期有效并可直接用于生成，请像密钥一样妥善保管，不要泄露给不信任的一方。
</Warning>

## 管理接口

### 列出素材组 / 素材

```bash
# 素材组（可选 GroupType 过滤：AIGC / LivenessFace）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Filter": {"GroupType": "AIGC"}}'

# 素材（可按组 / 状态 / 名称过滤）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Filter": {"GroupIds": ["group-20260709185838-dcnvd"], "Statuses": ["Active"]}}'
```

**过滤字段 `Filter`**

| 字段 | 适用 | 说明 |
| --- | --- | --- |
| `GroupType` | 素材组 | 素材组类型：`AIGC` / `LivenessFace` |
| `GroupIds` | 素材组 / 素材 | 按素材组 ID 数组过滤（命中任一即返回） |
| `Statuses` | 素材 | 按状态数组过滤：`Processing` / `Active` / `Failed` |
| `Name` | 素材组 / 素材 | 名称模糊匹配（≤64 字符） |

<Note>
为兼容旧写法，`Filter` 也接受单数形式 `GroupId` / `Status`（等价于只含一个元素的对应数组）。
</Note>

**排序**

- `SortBy`：素材支持 `CreateTime` / `UpdateTime` / `GroupId`，素材组支持 `CreateTime` / `UpdateTime`，默认 `CreateTime`。
- `SortOrder`：`Desc`（默认）/ `Asc`。

**分页（两种互斥模式）**

| 模式 | 入参 | 响应 |
| --- | --- | --- |
| 游标分页（默认，推荐） | `MaxResults` 每页条数 1~100（默认 10）、`NextToken` 下一页游标（首次不传） | `Result: {Items, NextToken?}`。**仅当还有下一页时才返回 `NextToken`**；未返回即代表已到末页 |
| 页码分页（兼容） | `PageNumber` ≥1（默认 1）、`PageSize` 1~100（默认 10） | `Result: {Items, TotalCount, PageNumber, PageSize}` |

<Warning>
两种分页模式不能混用：同时传 `PageNumber` / `PageSize` 与 `NextToken` / `MaxResults` 会返回 400 `InvalidParameter`。不传任何分页参数时默认走游标分页、每页 10 条。
</Warning>

游标分页翻页示例：

```bash
# 第一页（每页 20 条）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"Filter": {"GroupIds": ["group-20260709185838-dcnvd"]}, "MaxResults": 20}'
# => "Result": {"Items": [...], "NextToken": "<opaque cursor>"}

# 下一页：把上一页返回的 NextToken 原样回传（请勿自行解析或构造）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"Filter": {"GroupIds": ["group-20260709185838-dcnvd"]}, "MaxResults": 20, "NextToken": "<opaque cursor>"}'
# => "Result": {"Items": [...]}   # 无 NextToken 即已到末页
```

### 素材 / 素材组字段

素材项字段（`ListAssets` 时为 `Result.Items` 数组的每个元素，`GetAsset` 时直接作为 `Result` 返回）：

| 字段 | 说明 |
| --- | --- |
| `Id` | 素材 ID（`asset-` 开头） |
| `Name` | 素材名称 |
| `URL` | 素材访问链接（**始终返回**；处理中或无图时为空字符串，链接在每次查询时自动刷新） |
| `GroupId` | 所属素材组 ID |
| `AssetType` | 素材类型：`Image` / `Video` / `Audio`（注册时不传默认 `Image`） |
| `Status` | `Processing` / `Active` / `Failed` |
| `Moderation` | 审核策略对象，固定为 `{"Strategy": "Default"}` |
| `Error` | 失败原因对象 `{Code, Message}`，**始终返回**，无错误时两个字段均为空字符串 |
| `ProjectName` | 原样回显请求中的 `ProjectName`（默认 `default`） |
| `CreateTime` / `UpdateTime` | RFC-3339 UTC 时间字符串（如 `2026-07-09T19:01:43Z`） |

素材组项字段（`ListAssetGroups` 时为 `Result.Items` 数组的每个元素，`GetAssetGroup` 时直接作为 `Result` 返回）为：`Id`、`Name`、`Description`、`GroupType`、`ProjectName`、`CreateTime`、`UpdateTime`（**素材组没有 `Status` 字段**）。

<Tip>
`ProjectName` 是可选请求字段，仅用于在响应中原样回显、方便你按项目组织素材；不传时默认为 `default`。
</Tip>

### 重命名 / 修改描述

```bash
# 重命名素材组（可同时改描述，Description 上限 300 字；返回 {"Id": "..."}）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id": "group-20260709185838-dcnvd", "Name": "新的组名", "Description": "改后的描述"}'

# 重命名素材（返回 {"Id": "..."}）
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=UpdateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id": "asset-20260709190143-ntwhb", "Name": "新的素材名"}'
```

### 删除素材 / 素材组

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=DeleteAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" -d '{"Id": "asset-20260709190143-ntwhb"}'

curl -X POST "https://api.looprouter.com/api/v3/assets?Action=DeleteAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" -d '{"Id": "group-20260709185838-dcnvd"}'
```

删除操作成功返回 `"Result": {}`。

## 错误码

| HTTP | Code | 说明 |
| --- | --- | --- |
| 400 | `MissingParameter` / `InvalidParameter` / `InvalidAction` | 缺少 Action、必填字段，或 Action / GroupType / AssetType 不支持 |
| 401 | `Unauthorized` / `InvalidCredential` / `InvalidSignature` | API Key 或 AK/SK 无效，或火山请求签名不匹配 |
| 404 | `NotFound` | 素材/素材组不存在，或不属于当前账号 |
| 429 | `RateLimitExceeded` | 素材操作过于频繁（平台已自动排队重试后仍超限），请稍后重试 |
| 503 | `NoAvailableAssetChannel` | 当前账号的素材库服务暂未就绪，请联系我们开通 |
| 500 | `InternalError` | 素材库服务异常，Message 中包含具体原因 |

<Info>
素材注册操作在平台侧有自动排队机制：短时突发请求会先排队等待（最长 5 秒）而不是立即失败，超出等待窗口才返回 429。
</Info>

## 常见问题

<AccordionGroup>
  <Accordion title="素材可以在控制台网页上管理吗？">
    可以。控制台「资产管理」页面与本 API 操作的是同一个素材库，网页上传的素材同样可以在 API 中引用，反之亦然。
  </Accordion>
  <Accordion title="素材会保存多久？">
    素材 ID 长期有效。平台不长期存储素材原图，图片由官方素材库托管，访问链接会在每次查询时自动刷新。
  </Accordion>
  <Accordion title="不同账号之间的素材隔离吗？">
    是。素材、素材组、认证会话都绑定账号，跨账号查询、引用、删除均会返回 404。
  </Accordion>
  <Accordion title="想让角色一致性更好，怎么选素材？">
    建议同一角色上传两张图并同时引用：一张正面全身照 + 一张表情自然的面部特写。
  </Accordion>
  <Accordion title="真人照片上传报错？">
    真实人脸必须上传到真人认证产生的 `LivenessFace` 素材组。向普通 `AIGC` 组上传真人照片会在内容审核阶段失败（素材状态 `Failed`）。流程见 [真人认证接口](/asset-management/real-person)。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    真实人像素材的活体认证流程
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    端到端代码示例
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    生成参数详解
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/asset-management/asset-reference.md

# 素材引用生视频实战

> 端到端教程：创建素材组 → 注册素材 → 等待 Active → asset:// 引用生成 → 轮询下载成片

本页把 [素材库](/asset-management/asset-library) 与 [视频生成](/api-capabilities/seedance2/video-generation) 两组接口串成一条完整链路，实现**角色一致性**视频生成。

<Info>
本页聚焦代码链路。素材库逐接口说明见 [素材库 API](/asset-management/asset-library)；真实人像的认证前置步骤见 [真人认证接口](/asset-management/real-person)；生成参数全集见 [视频生成 API](/api-capabilities/seedance2/video-generation)。
</Info>

## 链路总览

<Steps>
  <Step title="创建素材组">`Action=CreateAssetGroup`（虚拟形象）或走真人认证获得素材组</Step>
  <Step title="注册素材">`Action=CreateAsset`，提交公网媒体 URL（图片 / 视频 / 音频，用 `AssetType` 指定，默认图片）</Step>
  <Step title="等待素材 Active">`Action=GetAsset` 每 3 秒轮询，直到 `Status: "Active"`</Step>
  <Step title="发起生成">`POST /api/v3/contents/generations/tasks`，`image_url` 填 `asset://素材ID`</Step>
  <Step title="轮询任务">每 15–30 秒查询，直到 `succeeded`</Step>
  <Step title="下载成片">从 `content.video_url` 下载（2 小时内有效，不带 Authorization 头）</Step>
</Steps>

<Warning>
提示词中用「图片1」「图片2」按 `content` 顺序指代素材，不要出现 `asset-` 开头的素材 ID 字面量。
</Warning>

## 鉴权方式

本页的素材管理 Action 支持两种认证方式：

- **API Key**：`Authorization: Bearer sk-...`，下方完整示例默认使用这种方式。
- **火山官方 AK/SK**：使用 API Key 所绑定的 AK/SK，按火山官方 `HMAC-SHA256` 方式签名；请求根路径为 `/`，Service 为 `ark`，Region 推荐 `cn-beijing`。

已有火山客户端只需将 Endpoint 和 AK/SK 替换为 LoopRouter 配置，Action、Version、JSON 请求体和响应解析不变。下面示例使用火山官方 Go SDK 对素材注册请求签名：

```go
package main

import (
  "bytes"
  "io"
  "net/http"
  "os"

  "github.com/volcengine/volc-sdk-golang/base"
)

func main() {
  body := []byte(`{"GroupId":"group-xxx","Name":"角色A-全身","URL":"https://example.com/character-a.png"}`)
  req, err := http.NewRequest(
    http.MethodPost,
    "https://api.looprouter.com/?Action=CreateAsset&Version=2024-01-01",
    bytes.NewReader(body),
  )
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/json")

  credentials := base.Credentials{
    AccessKeyID:     os.Getenv("LOOPROUTER_AK"),
    SecretAccessKey: os.Getenv("LOOPROUTER_SK"),
    Region:          "cn-beijing",
    Service:         "ark",
  }
  req = credentials.Sign(req)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  io.Copy(os.Stdout, resp.Body)
}
```

<Note>
AK/SK 仅替代素材管理与真人认证 Action 的 Bearer 认证。`POST /api/v3/contents/generations/tasks` 等视频生成接口仍使用 API Key；本地文件 `multipart/form-data` 上传也继续使用 API Key。
</Note>

## 完整代码

<CodeGroup>

```python Python
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {"Authorization": "Bearer sk-你的APIKey", "Accept-Encoding": "identity"}


def asset_action(name, body):
    resp = requests.post(
        f"{BASE}/api/v3/assets?Action={name}&Version=2024-01-01",
        headers=HEADERS, json=body,
    )
    resp.raise_for_status()
    return resp.json()["Result"]


def create_asset(group_id, name, url):
    result = asset_action("CreateAsset", {"GroupId": group_id, "Name": name, "URL": url})
    asset_id = result["Id"]
    deadline = time.time() + 90
    while time.time() < deadline:
        result = asset_action("GetAsset", {"Id": asset_id})
        if result["Status"] == "Active":
            return asset_id
        if result["Status"] == "Failed":
            raise RuntimeError(f"素材处理失败: {result.get('Error', {}).get('Message')}")
        time.sleep(3)
    raise TimeoutError("素材处理超时，请稍后用 GetAsset 复查")


def generate_video(content):
    resp = requests.post(
        f"{BASE}/api/v3/contents/generations/tasks",
        headers=HEADERS,
        json={
            "model": "doubao-seedance-2-0-260128",
            "content": content,
            "resolution": "720p",
            "ratio": "adaptive",
            "duration": 5,
        },
    )
    resp.raise_for_status()
    task_id = resp.json()["id"]
    while True:
        task = requests.get(
            f"{BASE}/api/v3/contents/generations/tasks/{task_id}", headers=HEADERS
        ).json()
        if task["status"] in ("succeeded", "failed", "cancelled", "expired"):
            return task
        time.sleep(20)


if __name__ == "__main__":
    group = asset_action("CreateAssetGroup", {"Name": "短剧角色A", "GroupType": "AIGC"})
    asset_id = create_asset(group["Id"], "角色A-全身", "https://example.com/character-a.png")

    task = generate_video([
        {"type": "text", "text": "图片1中的角色撑着伞走在雨中的巷子里，镜头跟随"},
        {"type": "image_url", "image_url": {"url": f"asset://{asset_id}"}, "role": "reference_image"},
    ])
    if task["status"] != "succeeded":
        raise SystemExit(f"生成失败: {task.get('error')}")

    video_url = task["content"]["video_url"]
    with requests.get(video_url, stream=True) as r:  # 不带 Authorization 头
        with open("output.mp4", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
```

```bash cURL 分步
KEY="sk-你的APIKey"
BASE="https://api.looprouter.com"

# 1. 创建素材组
curl -X POST "$BASE/api/v3/assets?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"Name": "短剧角色A", "GroupType": "AIGC"}'
# => Result.Id = group-20260709185838-dcnvd

# 2. 注册素材
curl -X POST "$BASE/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"GroupId": "group-20260709185838-dcnvd", "Name": "角色A-全身", "URL": "https://example.com/character-a.png"}'
# => Result.Id = asset-20260709190143-ntwhb

# 3. 轮询素材状态到 Active
curl -X POST "$BASE/api/v3/assets?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"Id": "asset-20260709190143-ntwhb"}'

# 4. 引用素材生成视频
curl -X POST "$BASE/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图片1中的角色撑着伞走在雨中的巷子里，镜头跟随"},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
    ],
    "resolution": "720p",
    "duration": 5
  }'
# => {"id": "task_xxxx"}

# 5. 轮询任务
curl "$BASE/api/v3/contents/generations/tasks/task_xxxx" -H "Authorization: Bearer $KEY"

# 6. 下载成片（不带 Authorization 头）
curl -o output.mp4 "<content.video_url>"
```

```javascript Node.js
const BASE = "https://api.looprouter.com";
const KEY = process.env.LOOPROUTER_API_KEY;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function assetAction(name, body) {
  const res = await fetch(`${BASE}/api/v3/assets?Action=${name}&Version=2024-01-01`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${KEY}` },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${name} failed: ${await res.text()}`);
  return (await res.json()).Result;
}

async function main() {
  const group = await assetAction("CreateAssetGroup", { Name: "短剧角色A", GroupType: "AIGC" });
  const { Id: assetId } = await assetAction("CreateAsset", {
    GroupId: group.Id,
    Name: "角色A-全身",
    URL: "https://example.com/character-a.png",
  });

  for (;;) {
    const asset = await assetAction("GetAsset", { Id: assetId });
    if (asset.Status === "Active") break;
    if (asset.Status === "Failed") throw new Error(`素材处理失败: ${asset.Error?.Message}`);
    await sleep(3000);
  }

  const createRes = await fetch(`${BASE}/api/v3/contents/generations/tasks`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${KEY}` },
    body: JSON.stringify({
      model: "doubao-seedance-2-0-260128",
      content: [
        { type: "text", text: "图片1中的角色撑着伞走在雨中的巷子里，镜头跟随" },
        { type: "image_url", image_url: { url: `asset://${assetId}` }, role: "reference_image" },
      ],
      resolution: "720p",
      duration: 5,
    }),
  });
  const { id } = await createRes.json();

  for (;;) {
    await sleep(20000);
    const task = await (
      await fetch(`${BASE}/api/v3/contents/generations/tasks/${id}`, {
        headers: { Authorization: `Bearer ${KEY}` },
      })
    ).json();
    if (task.status === "succeeded") return console.log("视频地址:", task.content.video_url);
    if (["failed", "cancelled", "expired"].includes(task.status))
      throw new Error(JSON.stringify(task.error));
  }
}

main();
```

</CodeGroup>

## 多素材进阶用法

- 一次请求最多引用 **9 张参考图**，`asset://`、公网 URL、Base64 可以混用；但真实人脸只能走 `asset://`（且需真人认证）。
- 可再叠加 **0–3 段参考视频** 与 **0–3 段参考音频**（音频不能单独出现，须至少配一张图或一段视频）；携带参考视频的请求自动享受视频输入计费折扣。
- 同一角色建议同时引用「全身照 + 面部特写」两张素材，提示词写「图片1为角色全身，图片2为角色面部」。
- 同一请求中的多个 `asset://` 素材必须来自同一账号。

## 常见报错速查

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 400 `asset not found or not active` | 素材还在 `Processing` 或 ID 写错 | 先 `GetAsset` 确认 `Active` |
| 400 素材引用相关 | 同一请求混用了不同账号的素材 | 同一请求只引用同一账号的素材，必要时重建素材组 |
| 403 内容审核 | 真实人脸未走认证直传 | 完成 [真人认证](/asset-management/real-person) 后用 `asset://` 引用 |
| 素材 `Failed` | 素材格式/尺寸/内容不合规，或与 `AssetType` 不匹配 | 按 `Error.Message` 修正后重新 `CreateAsset` |
| 视频 404 下载失败 | `video_url` 已过期（约 2 小时） | 重新查询任务获取新链接，尽快转存 |
| Python JSON 解析异常 | 网关 gzip 协商问题 | 请求头加 `Accept-Encoding: identity` |

## 相关页面

<CardGroup cols={3}>
  <Card title="能力总览" icon="circle-info" href="/api-capabilities/seedance2/overview">
    模型规格与定价
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    全部生成参数
  </Card>
  <Card title="素材库 API" icon="images" href="/asset-management/asset-library">
    素材管理接口
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/asset-management/real-person.md

# 真人认证接口

> 真实人像素材的活体认证全流程 API：发起认证、H5 刷脸、查询结果、上传真人素材

要在视频中使用**真实人物形象**，本人必须先通过活体认证（刷脸），认证通过后系统自动创建一个 `LivenessFace` 素材组，此后即可向该组上传这位真人的照片并在视频生成中引用。整个流程全 API 化，无需人工审核介入。

<Info>
该流程用于防止深度伪造：只有完成刷脸的本人形象才能被用于生成，未经认证的真实人脸图片会被内容审核拒绝。
</Info>

## 鉴权方式

真人认证与 [素材库](/asset-management/asset-library) 共用同一入口，支持 API Key 和火山官方 AK/SK 两种鉴权方式。两种方式访问同一份账号素材数据，并受对应 API Key 的额度、状态、有效期和访问策略约束。

### API Key（Bearer）

```
POST https://api.looprouter.com/api/v3/assets?Action=<操作名>&Version=2024-01-01
Authorization: Bearer sk-...
```

### 火山官方 AK/SK（HMAC-SHA256）

使用 API Key 所绑定的 AK/SK，按照火山官方 `HMAC-SHA256` 方式签名。已有火山客户端只需将 Endpoint 替换为 `https://api.looprouter.com`，并使用 LoopRouter API Key 页面生成的 AK/SK；Action、Version、请求体和响应解析保持不变。

火山签名请求使用根路径 `/`，Service 为 `ark`，Region 推荐 `cn-beijing`。下面示例使用火山官方 Go SDK 发起真人认证会话：

```go
package main

import (
  "bytes"
  "io"
  "net/http"
  "os"

  "github.com/volcengine/volc-sdk-golang/base"
)

func main() {
  body := []byte(`{"Name":"主播小李","Description":"直播切片项目"}`)
  req, err := http.NewRequest(
    http.MethodPost,
    "https://api.looprouter.com/?Action=CreateVisualValidateSession&Version=2024-01-01",
    bytes.NewReader(body),
  )
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/json")

  credentials := base.Credentials{
    AccessKeyID:     os.Getenv("LOOPROUTER_AK"),
    SecretAccessKey: os.Getenv("LOOPROUTER_SK"),
    Region:          "cn-beijing",
    Service:         "ark",
  }
  req = credentials.Sign(req)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  io.Copy(os.Stdout, resp.Body)
}
```

<Note>
AK/SK 可用于 `CreateVisualValidateSession`、`GetVisualValidateResult` 及其他 JSON 素材 Action。后续视频生成接口仍使用 API Key；本地文件 `multipart/form-data` 上传也继续使用 API Key。
</Note>

## 认证流程

<Steps>
  <Step title="发起认证会话 — CreateVisualValidateSession">

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "主播小李", "Description": "直播切片项目"}'
```

响应：

```json
{
  "ResponseMetadata": { "RequestId": "...", "Action": "CreateVisualValidateSession", "Version": "2024-01-01", "Service": "ark" },
  "Result": {
    "BytedToken": "a1b2c3d4e5f6a7b8",
    "H5Link": "https://api.looprouter.com/api/portrait/visual-validation/go/a1b2c3d4e5f6a7b8",
    "ExpireTime": 1752941700000
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `BytedToken` | 认证会话令牌，用于后续查询结果 |
| `H5Link` | 刷脸页面链接，**在手机浏览器中打开**（可将其生成二维码给被认证人扫码） |
| `ExpireTime` | 会话过期时间（毫秒时间戳），过期需重新发起 |

  </Step>
  <Step title="被认证人完成 H5 刷脸">
    将 `H5Link` 发给需要认证的本人，用手机打开并按提示完成人脸活体检测。会话有效期约 15 分钟。
  </Step>
  <Step title="查询认证结果 — GetVisualValidateResult">

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken": "a1b2c3d4e5f6a7b8"}'
```

三种结果：

**认证通过** — HTTP 200，返回真人素材组 ID：

```json
{ "Result": { "Status": "passed", "GroupId": "group-20260709185838-dcnvd" } }
```

**尚未完成** — HTTP 404，`Error.Code` 为 `NotFound.VisualValidateResult`。这不是异常，表示对方还没刷完脸，继续轮询即可（建议 3–5 秒一次）。

**失败 / 过期** — HTTP 200，`Result.Status` 为 `failed` 或 `expired`，失败时附带 `ResultCode` / `ResultMessage`。

  </Step>
  <Step title="向真人素材组上传照片 — CreateAsset">

```bash
curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260709185838-dcnvd",
    "Name": "小李-正面照",
    "URL": "https://example.com/xiaoli.jpg"
  }'
```

照片必须是**已认证本人**的清晰照片；上传其他人的照片会在内容审核阶段失败。随后用 `GetAsset` 轮询到 `Status: "Active"`。

  </Step>
  <Step title="在视频生成中引用真人素材">

```bash
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图片1中的人物坐在书桌前，对镜头介绍产品：\"大家好，今天给大家带来一款新品\""},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
    ],
    "resolution": "720p",
    "duration": 8
  }'
```

  </Step>
</Steps>

## Python 完整示例

```python
import time
import requests

BASE = "https://api.looprouter.com/api/v3/assets"
HEADERS = {"Authorization": "Bearer sk-你的APIKey", "Accept-Encoding": "identity"}

def action(name, body):
    resp = requests.post(f"{BASE}?Action={name}&Version=2024-01-01", headers=HEADERS, json=body)
    return resp.status_code, resp.json()

# 1. 发起认证
_, data = action("CreateVisualValidateSession", {"Name": "主播小李"})
token = data["Result"]["BytedToken"]
print("请用手机打开完成刷脸:", data["Result"]["H5Link"])

# 2. 轮询认证结果（404 = 还没刷完，继续等）
while True:
    code, data = action("GetVisualValidateResult", {"BytedToken": token})
    if code == 404:
        time.sleep(5)
        continue
    status = data["Result"]["Status"]
    if status == "passed":
        group_id = data["Result"]["GroupId"]
        print("认证通过，素材组:", group_id)
        break
    raise SystemExit(f"认证未通过: {data['Result']}")

# 3. 上传真人照片并等待 Active
_, data = action("CreateAsset", {
    "GroupId": group_id,
    "Name": "小李-正面照",
    "URL": "https://example.com/xiaoli.jpg",
})
asset_id = data["Result"]["Id"]
while True:
    _, data = action("GetAsset", {"Id": asset_id})
    if data["Result"]["Status"] in ("Active", "Failed"):
        break
    time.sleep(3)
print("素材状态:", data["Result"]["Status"], "→ 生成请求中引用 asset://" + asset_id)
```

## 注意事项

<Warning>
- `BytedToken` 与素材组、素材 ID 一样属于敏感凭据，请勿泄露。
- 认证会话约 **15 分钟**过期，请在发起后尽快完成刷脸；过期后重新调用 `CreateVisualValidateSession` 即可。
- 一次认证对应一个真人素材组；同一账号可为多位真人分别发起认证，各自维护素材组。
</Warning>

<Tip>
生成效果建议：同一真人上传「正面全身照 + 自然表情面部特写」两张素材并同时引用；提示词中用「图片1」「图片2」指代，台词放在双引号内可获得更好的口播效果。
</Tip>

## 错误码

| HTTP | Code | 说明 |
| --- | --- | --- |
| 400 | `MissingParameter` | 缺少 `BytedToken` / `GroupId` / `URL` 等必填字段 |
| 404 | `NotFound.VisualValidateResult` | 认证尚未完成（轮询中的正常状态） |
| 404 | `NotFound` | 会话/素材组不存在或不属于当前账号 |
| 429 | `RateLimitExceeded` | 操作过于频繁，稍后重试 |
| 503 | `NoAvailableAssetChannel` | 当前账号的素材库服务暂未就绪，请联系我们开通 |

## 相关文档

<CardGroup cols={3}>
  <Card title="素材库 API" icon="images" href="/asset-management/asset-library">
    素材组与素材的完整管理接口
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    从上传到生成的端到端示例
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    生成参数详解
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedance2/overview.md

# Seedance 2.0 能力总览

> Doubao Seedance 2.0 视频生成：模型介绍、技术规格、分辨率与宽高比、计费方式与常见问题

Seedance 2.0 是字节跳动豆包（Doubao）系列的旗舰视频生成模型，支持文生视频、首尾帧图生视频与多模态参考生成，并可同步生成与画面匹配的音频。LoopRouter 以与火山引擎方舟完全一致的接口对外提供该能力。

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    完整参数、三种生成模式、响应结构与错误码
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/create-video-task">
    在文档内直接发起真实请求
  </Card>
  <Card title="素材库" icon="images" href="/asset-management/asset-library">
    上传素材、管理素材组，获取 asset ID
  </Card>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    真实人像素材的活体认证全流程 API
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="多模态参考生成" icon="layer-group">
    单次请求最多组合 9 张参考图、3 段参考视频、3 段参考音频，保持角色与风格一致
  </Card>
  <Card title="音画同步" icon="volume-high">
    `generate_audio` 默认开启，人声、音效与配乐与画面同步生成
  </Card>
  <Card title="高分辨率" icon="expand">
    支持 480p / 720p / 1080p / 4k 多档输出，固定 24fps（可用档位依分组）
  </Card>
  <Card title="片段续接" icon="link">
    `return_last_frame` 返回末帧图，用作下一段视频的首帧，串联多个片段
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `doubao-seedance-2-0-260128` | 标准版，支持全部生成模式，最高 4k 输出（可用分辨率档位依分组） |

<Note>
模型名与火山官方快照版本号保持一致（`doubao-seedance-2-0-260128`），不需要 `ep-` 开头的接入点 ID。实际可用模型以控制台「模型广场」为准。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 首帧图生 / 首尾帧图生 / 多模态参考 |
| 分辨率 | `480p` / `720p` / `1080p` / `4k`，可用档位由[分组](/user-groups)决定：VIP 组全档位，补贴组 `720p` / `1080p`（分组外档位将被 400 拒绝，不扣费） |
| 宽高比 | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`（默认，跟随输入素材） |
| 时长 | 4–15 秒整数，或 `-1` 由模型决定；默认 5 秒 |
| 帧率 | 固定 24fps |
| 音频 | 默认生成同步音频，可用 `generate_audio: false` 关闭 |
| 参考素材 | ≤9 图 + ≤3 视频 + ≤3 音频（音频单段 2–15 秒） |
| 图片要求 | jpeg/png/webp/bmp/tiff/gif/heic/heif；宽高比 (0.4, 2.5)；边长 (300, 6000)px；小于 30MB |
| 提示词建议 | 中文 ≤500 字 / 英文 ≤1000 词；台词用双引号包裹 |
| 任务模式 | 异步任务：`queued → running → succeeded / failed / cancelled / expired` |
| 成片链接 | `content.video_url` 约 2 小时有效，请及时转存 |

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v3/contents/generations/tasks` | 创建视频生成任务 |
| GET | `/api/v3/contents/generations/tasks/{task_id}` | 查询单个任务 |
| GET | `/api/v3/contents/generations/tasks` | 任务列表（分页/筛选） |
| DELETE | `/api/v3/contents/generations/tasks/{task_id}` | 取消/删除任务 |
| POST | `/api/v3/assets?Action=...&Version=2024-01-01` | 素材库与真人认证（[详情](/asset-management/asset-library)） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。路径中的 `/api` 前缀不能省略。
</Tip>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程：

<Steps>
  <Step title="提交预扣">
    任务创建成功后，按请求参数（分辨率、时长）预估并预扣一笔额度，日志中心会产生一条预扣记录。
  </Step>
  <Step title="完成结算">
    任务成功后按上游返回的实际用量（`usage.total_tokens`，约等于 时长 × 输出宽 × 输出高 × 24 ÷ 1024）重新计算，多退少补；任务失败则全额退回预扣。
  </Step>
</Steps>

<Info>
**视频输入折扣**：当请求 `content` 中包含参考视频（`video_url`）时，系统自动应用带视频输入的优惠倍率，无需额外传参。

**不扣费场景**：参数校验失败（400）、内容审核拒绝（403）均不产生费用。
</Info>

<Warning>
使用 `duration: -1`（模型自选时长）或 `ratio: adaptive` 时，实际费用以任务成功后响应中回填的真实时长/分辨率为准，与预扣金额可能存在差额，结算时自动多退少补。
</Warning>

各分辨率档位的具体单价请以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率（具体折扣以商务对接约定为准），分组同时决定可用的分辨率档位。

## 限流与重试

- 平台按渠道维度做 RPM 智能调度：并发高峰时任务会短暂排队而不是直接失败。
- 收到 429（`当前分组上游负载已饱和，请稍后再试`）或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔 15–30 秒；720p / 5 秒视频的典型生成耗时约 2–5 分钟。

## 常见问题

<AccordionGroup>
  <Accordion title="为什么创建任务只返回一个 id，没有视频？">
    这是异步任务接口：创建仅入队并返回任务 ID，需轮询 `GET /api/v3/contents/generations/tasks/{id}` 直到状态变为 `succeeded`，再从 `content.video_url` 下载成片。
  </Accordion>
  <Accordion title="成功状态是 completed 还是 succeeded？">
    是 `succeeded`。判断终态请匹配 `succeeded / failed / cancelled / expired` 四个值。
  </Accordion>
  <Accordion title="支持哪些分辨率？为什么传 480p 会报错？">
    可用档位由 API Key 所在的[分组](/user-groups)决定：VIP 组支持 `480p`、`720p`、`1080p`、`4k` 全档位，补贴组支持 `720p`、`1080p`。传入分组不支持的档位会返回 400（错误信息会列出当前可用档位），且不扣费。
  </Accordion>
  <Accordion title="支持 callback 回调吗？">
    不支持。`callback_url` 会被 400 拒绝，请使用轮询获取任务结果。
  </Accordion>
  <Accordion title="视频链接过期了怎么办？">
    `content.video_url` 是约 2 小时有效的临时链接，过期后重新调用查询接口会得到新的下载链接；但任务本身也有保留期限，请在生成后尽快转存到自己的存储。
  </Accordion>
  <Accordion title="能直接用真人照片作参考图吗？">
    不能。出于防深度伪造要求，真实人脸图片不能直接放入 `image_url`（会被内容审核 403 拒绝）。需先完成 [真人认证](/asset-management/real-person)，把照片上传到认证素材组，再以 `asset://素材ID` 引用。
  </Accordion>
  <Accordion title="同一个 seed 能得到完全相同的视频吗？">
    不能保证完全一致。相同 seed 与参数会得到高度相近的结果，适合微调提示词时保持整体构图稳定。
  </Accordion>
  <Accordion title="Python 请求报 JSON 解析错误 / 响应被截断？">
    在请求头加 `Accept-Encoding: identity`。个别网络环境下网关 gzip 协商会导致 `requests` 解码异常。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    参数与响应详解
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    端到端角色一致性教程
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedance2/video-generation.md

# Seedance 2.0 视频生成 API

> 任务式异步接口：文生视频、首尾帧图生视频、多模态参考生视频，路径与火山引擎方舟完全一致

Seedance 2.0 视频生成采用**异步任务**模式：先提交任务拿到任务 ID，再轮询查询接口获取成片。接口路径、请求体、响应结构与火山引擎方舟保持一致，已有的官方示例代码只需替换 Base URL 与 API Key 即可运行。

<Info>
想先在浏览器里体验？打开 [API 参考 → 创建视频生成任务](/api-reference/create-video-task)，填入你的 `sk-` API Key 即可**试一试**在线发起真实请求。
</Info>

<Tip>
文生视频、图生视频、多模态参考共用同一个接口，仅靠 `content` 数组的组合区分模式。模型清单、定价与常见问题见 [能力总览](/api-capabilities/seedance2/overview)。
</Tip>

<Warning>
**接入前请注意以下差异点，可以避开绝大多数排障时间：**

1. Base URL 为 `https://api.looprouter.com`，完整路径是 `/api/v3/contents/generations/tasks`，`/api` 前缀不能省略。
2. `resolution` 可用档位由 [API Key 所在分组](/user-groups)决定：VIP 组支持 `480p`、`720p`、`1080p`、`4k` 全档位，补贴组支持 `720p`、`1080p`。传入分组外的档位会直接返回 400，不会扣费。
3. 本接口**不支持** `callback_url` 回调，传入会返回 400；请使用轮询查询任务状态。
4. 成功状态是 `succeeded`（不是 `completed`）；成片 `content.video_url` 为临时链接，请在 2 小时内转存。
5. Python `requests` 用户建议加请求头 `Accept-Encoding: identity`，避免个别网络环境下 gzip 解码异常导致响应截断。
</Warning>

## 代码示例

<CodeGroup>

```bash 创建任务（cURL）
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

# 返回：{"id": "task_xxxx"} —— 只返回任务 ID，视频需轮询查询接口获取
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {
    "Authorization": "Bearer sk-你的APIKey",
    "Accept-Encoding": "identity",  # 避免个别环境 gzip 解码异常
}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/api/v3/contents/generations/tasks",
    headers=HEADERS,
    json={
        "model": "doubao-seedance-2-0-260128",
        "content": [
            {"type": "text", "text": "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过"}
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
        # "generate_audio": True,   # 默认开启同步音频
        # "seed": 42,               # 固定随机种子，结果更可复现
    },
)
resp.raise_for_status()
task_id = resp.json()["id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 15~30 秒一次）
while True:
    task = requests.get(
        f"{BASE}/api/v3/contents/generations/tasks/{task_id}",
        headers=HEADERS,
    ).json()
    status = task["status"]
    print("当前状态:", status)
    if status in ("succeeded", "failed", "cancelled", "expired"):
        break
    time.sleep(20)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "succeeded":
    video_url = task["content"]["video_url"]
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open("output.mp4", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
else:
    print("任务未成功:", task.get("error"))
```

```python 图生视频与多模态参考（Python）
# 模式二：首尾帧图生视频 —— 用两张图约束视频的第一帧和最后一帧
first_last_frame_body = {
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {"type": "text", "text": "镜头缓缓推进，人物转身微笑"},
        {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
        {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"},
    ],
    "resolution": "1080p",
    "duration": 5,
}

# 模式三：多模态参考 —— 参考图 / 参考视频 / 参考音频自由组合
multimodal_body = {
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {"type": "text", "text": "图片1中的角色在草地上奔跑，参考视频1的运镜节奏"},
        {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"},
        # {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"},
        # {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"},
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": -1,  # -1 表示由模型自行决定时长，按实际产出计费
}
```

```javascript Node.js
const BASE = "https://api.looprouter.com";
const KEY = process.env.LOOPROUTER_API_KEY;

async function main() {
  // 创建任务
  const createRes = await fetch(`${BASE}/api/v3/contents/generations/tasks`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${KEY}`,
    },
    body: JSON.stringify({
      model: "doubao-seedance-2-0-260128",
      content: [
        { type: "text", text: "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过" },
      ],
      resolution: "720p",
      ratio: "16:9",
      duration: 5,
    }),
  });
  const { id } = await createRes.json();
  console.log("任务已创建:", id);

  // 轮询
  for (;;) {
    await new Promise((r) => setTimeout(r, 20000));
    const task = await (
      await fetch(`${BASE}/api/v3/contents/generations/tasks/${id}`, {
        headers: { Authorization: `Bearer ${KEY}` },
      })
    ).json();
    console.log("当前状态:", task.status);
    if (["succeeded", "failed", "cancelled", "expired"].includes(task.status)) {
      if (task.status === "succeeded") console.log("视频地址:", task.content.video_url);
      else console.error("任务未成功:", task.error);
      break;
    }
  }
}

main();
```

```bash 查询任务（cURL）
curl "https://api.looprouter.com/api/v3/contents/generations/tasks/task_xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

</CodeGroup>

## 请求参数速查

`POST /api/v3/contents/generations/tasks`，请求头 `Authorization: Bearer sk-...`。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 如 `doubao-seedance-2-0-260128`，可用模型以控制台「模型广场」为准 |
| `content` | array | 是 | — | 生成素材数组，见下方[内容项说明](#content-数组) |
| `resolution` | string | 否 | 上游默认 | `480p` / `720p` / `1080p` / `4k`，可用档位依[分组](/user-groups)（VIP 组全档位，补贴组 `720p` / `1080p`），分组外档位返回 400 且不扣费 |
| `ratio` | string | 否 | `adaptive` | `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive` |
| `duration` | int | 否 | `5` | 输出时长（秒），范围 4–15；传 `-1` 由模型决定并按实际产出计费 |
| `generate_audio` | bool | 否 | `true` | 是否生成与画面同步的音频（人声/音效/配乐） |
| `watermark` | bool | 否 | `false` | 是否叠加 AI 生成水印 |
| `seed` | int | 否 | `-1` | 随机种子；相同种子产出相近（非完全一致）的结果 |
| `return_last_frame` | bool | 否 | `false` | 成功后额外返回末帧图片，便于多段续接 |
| `execution_expires_after` | int | 否 | `172800` | 任务执行超时（秒），超时未完成转为 `expired` |

<Warning>
`callback_url` 在本平台**不受支持**，传入会返回 400。Seedance 1.x 的 `frames`、`camera_fixed` 等参数对 2.0 模型无效，请勿依赖。
</Warning>

### content 数组

每个元素为一个内容项，`type` 决定其结构：

| type | 结构 | role 取值 | 说明 |
| --- | --- | --- | --- |
| `text` | `{"type":"text","text":"..."}` | — | 提示词。建议中文 ≤500 字、英文 ≤1000 词；台词放在双引号内可提升配音效果 |
| `image_url` | `{"type":"image_url","image_url":{"url":"..."},"role":"..."}` | `first_frame` / `last_frame` / `reference_image` | 支持公网 URL、Base64 data URI、`asset://素材ID` |
| `video_url` | `{"type":"video_url","video_url":{"url":"..."},"role":"reference_video"}` | `reference_video` | 参考视频，最多 3 个；携带视频输入享受[计费折扣](/api-capabilities/seedance2/overview#模型定价) |
| `audio_url` | `{"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"}` | `reference_audio` | 参考音频 wav/mp3，单段 2–15 秒，最多 3 段，不能单独出现 |

图片要求：jpeg/png/webp/bmp/tiff/gif/heic/heif，宽高比 (0.4, 2.5)，边长 (300, 6000) 像素，小于 30MB。**真实人脸图片不能直接作为参考图**，需先走 [素材库](/asset-management/asset-library) 与 [真人认证](/asset-management/real-person)，再以 `asset://` 引用。

### 生成模式

| 模式 | content 组合 |
| --- | --- |
| 文生视频 | 1 个 `text` |
| 首帧图生视频 | 可选 `text` + 1 个 `image_url`（role 可省略） |
| 首尾帧图生视频 | 可选 `text` + 2 个 `image_url`（role 必须分别为 `first_frame`、`last_frame`） |
| 多模态参考 | `text` + 0–9 张参考图 + 0–3 个参考视频 + 0–3 段参考音频（至少 1 图或 1 视频） |

三种图片用法互斥：同一请求中不能混用首帧/首尾帧与参考图。

## 查询任务

`GET /api/v3/contents/generations/tasks/{task_id}`

任务状态机：`queued → running → succeeded / failed / cancelled / expired`。任务记录长期保留，可随时回查。

成功响应示例：

```json
{
  "id": "task_xxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://api.looprouter.com/.../output.mp4?...",
    "last_frame_url": ""
  },
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  },
  "seed": 42,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "generate_audio": true,
  "created_at": 1752940800,
  "updated_at": 1752941020
}
```

<Warning>
成片地址在 `content.video_url` 字段，为**临时签名链接（约 2 小时有效）**，请及时转存；下载时请求中**不要**携带 `Authorization` 头。
</Warning>

<Info>
`usage.total_tokens` 为上游按「时长 × 分辨率像素 × 帧率」口径折算的视频 token 数，是结算依据。使用 `duration: -1` 或 `ratio: adaptive` 时，以响应中回填的实际值为准。
</Info>

## 任务列表与取消

本平台在原厂接口之外额外提供两个管理接口：

**列出任务** — `GET /api/v3/contents/generations/tasks`

| 查询参数 | 说明 |
| --- | --- |
| `page_num` | 页码，默认 1 |
| `page_size` | 每页数量，默认 20，最大 500 |
| `filter.status` | 按状态过滤：`queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `filter.model` | 按模型过滤 |
| `filter.task_ids` | 按任务 ID 列表过滤 |

响应为 `{"items": [...], "total": n}`，元素结构与查询单个任务一致。

**取消/删除任务** — `DELETE /api/v3/contents/generations/tasks/{task_id}`

排队中的任务可以取消；`running` 状态的任务不可取消（返回 400 `invalid_task_status`）。成功返回 `{}`。

## 错误响应

所有错误采用与火山引擎一致的结构：

```json
{
  "error": {
    "code": "invalid_request",
    "message": "具体错误描述 (request id: ...)",
    "param": "",
    "type": "BadRequest"
  }
}
```

| HTTP 状态码 | type | 常见原因 |
| --- | --- | --- |
| 400 | `BadRequest` | 缺少 `model`/`content`；`resolution` 不在当前[分组](/user-groups)可用档位内；传了 `callback_url`；取消运行中任务 |
| 401 | `Unauthorized` | API Key 缺失或无效 |
| 403 | `Forbidden` | 令牌无权访问该模型；内容审核未通过（如真实人脸直传） |
| 404 | `NotFound` | 任务 ID 不存在或不属于当前账号 |
| 429 | `RateLimitExceeded` | 当前分组上游负载已饱和，请稍后再试 |
| 5xx | `InternalServerError` | 服务端异常，建议指数退避后重试 |

<Info>
429 与 5xx 建议采用指数退避重试（如 2s → 4s → 8s）。参数校验失败（400）与内容审核拒绝（403）**均不扣费**；已预扣的失败任务会自动退款。
</Info>

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/seedance2/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    从上传素材到角色一致性生成的完整链路
  </Card>
  <Card title="在线调试" icon="flask" href="/api-reference/create-video-task">
    在文档内直接试一试
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedance25/overview.md

# Seedance 2.5 能力总览

> Doubao Seedance 2.5 视频生成：素材规格、输出格式与编码、任务类型约束、计费方式与常见问题

Seedance 2.5 是字节跳动豆包（Doubao）系列的视频生成模型，支持文生视频、首帧 / 首尾帧图生视频、多模态参考、视频编辑与视频延长，**单次生成最长 30 秒**，并可同步生成音频。LoopRouter 使用火山引擎方舟兼容接口；从 2.0 迁移时，还需检查素材数量、任务类型、宽高比和输出格式，不能只替换 `model`。

<Note>
平台支持 `output_format`（`mp4` / `mov`）和 `omni_reference_task_type`（`auto` / `reference` / `edit` / `extend`），查询结果会在上游返回时提供 `output_format`。这两个参数仅适用于 Seedance 2.5；不传时使用官方默认值。详见 [输出格式与任务类型参数](/api-capabilities/seedance25/video-generation#输出格式与任务类型参数)。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance25/video-generation">
    请求参数、素材与编码规格、任务类型约束、响应与错误码
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/create-video-task">
    在文档内直接发起真实请求
  </Card>
  <Card title="素材库" icon="images" href="/asset-management/asset-library">
    上传素材、管理素材组，获取 asset ID
  </Card>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    真实人像素材的活体认证全流程 API
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="更长单段时长" icon="clock">
    时长范围扩展到 4–30 秒，一次生成即可覆盖更完整的镜头叙事
  </Card>
  <Card title="多模态参考生成" icon="layer-group">
    最多 30 张参考图、10 个参考视频、10 段参考音频，也支持仅输入音频
  </Card>
  <Card title="音画同步" icon="volume-high">
    `generate_audio` 默认开启，人声、音效与配乐与画面同步生成
  </Card>
  <Card title="高清分辨率" icon="expand">
    支持 480p / 720p / 1080p 三档输出，固定 24fps
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `doubao-seedance-2-5-260628` | 新一代标准版，支持全部生成模式，时长最长 30 秒，输出分辨率 480p / 720p / 1080p |

<Note>
模型名与火山官方快照版本号保持一致（`doubao-seedance-2-5-260628`），不需要 `ep-` 开头的接入点 ID。实际可用模型以控制台「模型广场」为准。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 首帧图生 / 首尾帧图生 / 多模态参考（参考生成、编辑、延长） |
| 分辨率 | `480p` / `720p` / `1080p`，默认 `720p`（Seedance 2.5 暂不支持 `4k`，传入 `4k` 将被 400 拒绝，不扣费） |
| 宽高比 | 默认 `adaptive`；文生视频 / 参考生成可选 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`；首帧 / 首尾帧、编辑、延长任务仅支持 `adaptive` |
| 时长 | **4–30 秒**整数，默认 `-1`（智能选择）；编辑任务仅支持 `-1`，时长跟随待编辑视频 |
| 帧率 | 固定 24fps |
| 输出格式 | `mp4`（默认）/ `mov`，通过 `output_format` 指定；MOV 请求保留上游原生规格产物 |
| 输出编码 | 官方 1080p 规格为 10bit、H.265/HEVC；MOV 另有 H.264 + yuv444p + PCM 的格式说明，见 [输出格式与编码](/api-capabilities/seedance25/video-generation#输出格式与编码) |
| 音频 | 默认生成同步音频，输出为单声道；可用 `generate_audio: false` 关闭 |
| 参考素材 | ≤30 图 + ≤10 视频 + ≤10 音频；视频总时长 ≤30 秒，音频总时长 ≤30 秒；支持仅输入音频 |
| 图片要求 | jpeg/png/webp/bmp/tiff/gif/heic/heif；宽高比 `[0.4, 2.5]`；边长 `[300, 6000]`px；单张小于 30 MB |
| 视频要求 | MP4 / MOV；视频编码 H.264/AVC 或 H.265/HEVC；24–60fps；单个 ≤200 MB；非编辑任务 2–30 秒，编辑任务 4–30 秒 |
| 音频要求 | WAV / MP3；单段 2–30 秒；单段 ≤15 MB |
| 提示词建议 | 中文 ≤500 字 / 英文 ≤1000 词；台词用双引号包裹 |
| 任务模式 | 异步任务：`queued → running → succeeded / failed / cancelled / expired` |
| 成片链接 | `content.video_url` 为临时链接；官方原始视频 URL 有效期 24 小时、最多下载 100 次；平台转存链接以实际存储策略为准 |

<Tip>
从 2.0 迁移：2.5 的时长上限为 30 秒，参考素材上限提升至 30 图 / 10 视频 / 10 音频，支持仅输入音频；输出最高 `1080p`，不支持 `4k`。首帧 / 首尾帧、编辑、延长任务必须使用 `ratio: adaptive`，编辑任务还必须使用 `duration: -1`。`output_format` 和 `omni_reference_task_type` 是 2.5 专属参数，切回 2.0 时应移除。
</Tip>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v3/contents/generations/tasks` | 创建视频生成任务 |
| GET | `/api/v3/contents/generations/tasks/{task_id}` | 查询单个任务 |
| GET | `/api/v3/contents/generations/tasks` | 任务列表（分页/筛选） |
| DELETE | `/api/v3/contents/generations/tasks/{task_id}` | 取消/删除任务 |
| POST | `/api/v3/assets?Action=...&Version=2024-01-01` | 素材库与真人认证（[详情](/asset-management/asset-library)） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。路径中的 `/api` 前缀不能省略。
</Tip>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程：

<Steps>
  <Step title="提交预扣">
    任务创建成功后，按请求参数（分辨率、时长）预估并预扣一笔额度，日志中心会产生一条预扣记录。时长越长、分辨率越高，预扣越多。
  </Step>
  <Step title="完成结算">
    任务成功后按上游返回的实际用量（`usage.total_tokens`，约等于 时长 × 输出宽 × 输出高 × 24 ÷ 1024）重新计算，多退少补；任务失败则全额退回预扣。
  </Step>
</Steps>

<Info>
**视频输入折扣**：当请求 `content` 中包含参考视频（`video_url`）时，系统自动应用带视频输入的优惠倍率，无需额外传参。

**不扣费场景**：参数校验失败（400）、内容审核拒绝（403）均不产生费用。
</Info>

<Warning>
使用 `duration: -1`（模型自选时长）或 `ratio: adaptive` 时，实际费用以任务成功后响应中回填的真实时长/分辨率为准，与预扣金额可能存在差额，结算时自动多退少补。长时长任务（如 30 秒）请预留充足余额。
</Warning>

各分辨率档位的具体单价请以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率（具体折扣以商务对接约定为准），分组同时决定可用的分辨率档位。

## 限流与重试

- 平台按渠道维度做 RPM 智能调度：并发高峰时任务会短暂排队而不是直接失败。
- 收到 429（`当前分组上游负载已饱和，请稍后再试`）或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔 15–30 秒；时长越长生成耗时越久，长视频请适当延长轮询周期与超时时间。

## 常见问题

<AccordionGroup>
  <Accordion title="2.5 和 2.0 的接口有什么区别？">
    两者使用相同端点，但 2.5 的时长、素材数量、仅音频输入、输出格式与任务类型约束都有变化。尤其是首帧 / 首尾帧、编辑、延长任务仅支持 `ratio: adaptive`，编辑任务仅支持 `duration: -1`。请按 [视频生成 API](/api-capabilities/seedance25/video-generation) 检查参数，不能只替换模型名。
  </Accordion>
  <Accordion title="为什么创建任务只返回一个 id，没有视频？">
    这是异步任务接口：创建仅入队并返回任务 ID，需轮询 `GET /api/v3/contents/generations/tasks/{id}` 直到状态变为 `succeeded`，再从 `content.video_url` 下载成片。
  </Accordion>
  <Accordion title="成功状态是 completed 还是 succeeded？">
    是 `succeeded`。判断终态请匹配 `succeeded / failed / cancelled / expired` 四个值。
  </Accordion>
  <Accordion title="支持哪些分辨率？">
    Seedance 2.5 支持 `480p`、`720p`、`1080p` 三档，默认 `720p`；暂不支持 `4k`（传入 `4k` 会返回 400 且不扣费）。
  </Accordion>
  <Accordion title="支持 callback 回调吗？">
    不支持。`callback_url` 会被 400 拒绝，请使用轮询获取任务结果。
  </Accordion>
  <Accordion title="MP4 和 MOV 的编码、播放兼容性有什么区别？">
    官方默认输出 MP4，1080p 规格采用 10bit 与 H.265/HEVC，播放器需支持相应解码。设置 `output_format: mov` 可选择面向专业后期的 MOV，官方格式说明为 H.264 + yuv444p + PCM，部分播放器不兼容。MOV 请求保留上游原生规格产物。输入视频的容器与编码要求见 [素材要求](/api-capabilities/seedance25/video-generation#素材要求)。
  </Accordion>
  <Accordion title="视频链接过期了怎么办？">
    官方原始视频 URL 有效期为 24 小时，Seedance 2.5 视频 URL 最多下载 100 次；平台转存链接的有效期以实际存储策略为准。请在任务成功后尽快下载并转存，不要依赖重新查询来刷新过期链接。任务记录仍可查询不代表视频文件永久可下载。
  </Accordion>
  <Accordion title="能直接用真人照片作参考图吗？">
    不能。出于防深度伪造要求，真实人脸图片不能直接放入 `image_url`（会被内容审核 403 拒绝）。需先完成 [真人认证](/asset-management/real-person)，把照片上传到认证素材组，再以 `asset://素材ID` 引用。
  </Accordion>
  <Accordion title="Python 请求报 JSON 解析错误 / 响应被截断？">
    在请求头加 `Accept-Encoding: identity`。个别网络环境下网关 gzip 协商会导致 `requests` 解码异常。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance25/video-generation">
    参数与响应详解
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    端到端角色一致性教程
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedance25/video-generation.md

# Seedance 2.5 视频生成 API

> Seedance 2.5 异步视频生成：MP4/MOV 输出、参考生成与编辑/延长参数、素材格式与编码、任务约束

Seedance 2.5 视频生成采用**异步任务**模式：先提交任务拿到任务 ID，再轮询查询接口获取成片。LoopRouter 使用火山引擎方舟兼容端点，支持最长 30 秒、最高 `1080p` 输出，并支持 `output_format` 和 `omni_reference_task_type`。从 [Seedance 2.0](/api-capabilities/seedance2/video-generation) 迁移时，需重新检查素材数量、任务类型及 `ratio` / `duration` 限制。

<Info>
想先在浏览器里体验？打开 [API 参考 → 创建视频生成任务](/api-reference/create-video-task)，填入你的 `sk-` API Key 即可**试一试**在线发起真实请求。
</Info>

<Tip>
文生视频、图生视频、多模态参考共用同一个接口，模型根据 `content` 素材及提示词判断任务类型。模型清单、定价与常见问题见 [能力总览](/api-capabilities/seedance25/overview)。
</Tip>

<Warning>
**接入前请注意以下差异点，可以避开绝大多数排障时间：**

1. Base URL 为 `https://api.looprouter.com`，完整路径是 `/api/v3/contents/generations/tasks`，`/api` 前缀不能省略。
2. `resolution` 支持 `480p` / `720p` / `1080p`（默认 `720p`；Seedance 2.5 暂不支持 `4k`）。传入 `4k` 会直接返回 400，不会扣费。
3. `duration` 默认 `-1`，支持 4–30 秒整数；编辑任务仅支持 `-1`。首帧 / 首尾帧、编辑、延长任务的 `ratio` 仅支持 `adaptive`。
4. 本接口**不支持** `callback_url` 回调，传入会返回 400；请使用轮询查询任务状态。
5. 成功状态是 `succeeded`（不是 `completed`）；成片 `content.video_url` 为临时链接，请及时转存，详见[查询任务](#查询任务)。
6. Python `requests` 用户建议加请求头 `Accept-Encoding: identity`，避免个别网络环境下 gzip 解码异常导致响应截断。
7. `output_format` / `omni_reference_task_type` 仅适用于 Seedance 2.5。平台原样透传显式值，不传时使用上游默认的 `mp4` / `auto`；参数合法性与任务类型约束由上游校验。
</Warning>

## 代码示例

<CodeGroup>

```bash 创建任务（cURL）
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 10
  }'

# 返回：{"id": "task_xxxx"} —— 只返回任务 ID，视频需轮询查询接口获取
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {
    "Authorization": "Bearer sk-你的APIKey",
    "Accept-Encoding": "identity",  # 避免个别环境 gzip 解码异常
}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/api/v3/contents/generations/tasks",
    headers=HEADERS,
    json={
        "model": "doubao-seedance-2-5-260628",
        "content": [
            {"type": "text", "text": "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过"}
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 10,          # 2.5 支持 4~30 秒
        "output_format": "mp4",  # 可改为 mov，用于专业后期
        # "generate_audio": True,  # 默认开启同步音频
    },
)
resp.raise_for_status()
task_id = resp.json()["id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 15~30 秒一次；长时长任务可适当延长）
while True:
    task = requests.get(
        f"{BASE}/api/v3/contents/generations/tasks/{task_id}",
        headers=HEADERS,
    ).json()
    status = task["status"]
    print("当前状态:", status)
    if status in ("succeeded", "failed", "cancelled", "expired"):
        break
    time.sleep(20)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "succeeded":
    video_url = task["content"]["video_url"]
    output_format = task.get("output_format", "mp4")
    filename = f"output.{output_format}"
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open(filename, "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存", filename)
else:
    print("任务未成功:", task.get("error"))
```

```python 图生视频与多模态参考（Python）
# 模式二：首尾帧图生视频 —— 用两张图约束视频的第一帧和最后一帧
first_last_frame_body = {
    "model": "doubao-seedance-2-5-260628",
    "content": [
        {"type": "text", "text": "镜头缓缓推进，人物转身微笑"},
        {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
        {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"},
    ],
    "resolution": "720p",
    "ratio": "adaptive",  # 2.5 首帧 / 首尾帧任务仅支持 adaptive
    "duration": 8,
}

# 模式三：多模态参考 —— 参考图 / 参考视频 / 参考音频自由组合
multimodal_body = {
    "model": "doubao-seedance-2-5-260628",
    "omni_reference_task_type": "reference",
    "content": [
        {"type": "text", "text": "根据图片1中的角色生成一段在草地上奔跑的新视频"},
        {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"},
        # {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"},
        # {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"},
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": -1,  # -1 表示由模型自行决定时长，按实际产出计费
}
```

```javascript Node.js
const BASE = "https://api.looprouter.com";
const KEY = process.env.LOOPROUTER_API_KEY;

async function main() {
  // 创建任务
  const createRes = await fetch(`${BASE}/api/v3/contents/generations/tasks`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${KEY}`,
    },
    body: JSON.stringify({
      model: "doubao-seedance-2-5-260628",
      content: [
        { type: "text", text: "雨后的城市街道，霓虹灯倒映在积水中，一只橘猫从画面左侧慢慢走过" },
      ],
      resolution: "720p",
      ratio: "16:9",
      duration: 10,
    }),
  });
  const { id } = await createRes.json();
  console.log("任务已创建:", id);

  // 轮询
  for (;;) {
    await new Promise((r) => setTimeout(r, 20000));
    const task = await (
      await fetch(`${BASE}/api/v3/contents/generations/tasks/${id}`, {
        headers: { Authorization: `Bearer ${KEY}` },
      })
    ).json();
    console.log("当前状态:", task.status);
    if (["succeeded", "failed", "cancelled", "expired"].includes(task.status)) {
      if (task.status === "succeeded") console.log("视频地址:", task.content.video_url);
      else console.error("任务未成功:", task.error);
      break;
    }
  }
}

main();
```

```bash 查询任务（cURL）
curl "https://api.looprouter.com/api/v3/contents/generations/tasks/task_xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

</CodeGroup>

## 请求参数速查

`POST /api/v3/contents/generations/tasks`，请求头 `Authorization: Bearer sk-...`。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 如 `doubao-seedance-2-5-260628`，可用模型以控制台「模型广场」为准 |
| `content` | array | 是 | — | 生成素材数组，见下方[内容项说明](#content-数组) |
| `resolution` | string | 否 | `720p` | `480p` / `720p` / `1080p`（Seedance 2.5 暂不支持 `4k`，传入 `4k` 返回 400 且不扣费） |
| `ratio` | string | 否 | `adaptive` | 文生视频 / 参考生成可选 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`；首帧 / 首尾帧、编辑、延长任务仅支持 `adaptive` |
| `duration` | int | 否 | `-1` | 输出时长（秒），范围 **4–30**；`-1` 表示智能选择；编辑任务必须为 `-1`，输出时长跟随待编辑视频 |
| `generate_audio` | bool | 否 | `true` | 是否生成与画面同步的单声道音频（人声/音效/配乐） |
| `watermark` | bool | 否 | `false` | 是否叠加 AI 生成水印 |
| `output_format` | string | 否 | `mp4` | `mp4` / `mov`；输出容器格式，MOV 请求保留上游原生输出 |
| `omni_reference_task_type` | string | 否 | `auto` | `auto` / `reference` / `edit` / `extend`；多模态参考任务的子类型引导，详见下方[任务约束](#任务类型与参数约束) |
| `return_last_frame` | bool | 否 | `false` | 成功后额外返回无水印 PNG 末帧图，尺寸与输出视频一致，便于多段续接 |
| `execution_expires_after` | int | 否 | `172800` | 从任务创建时间起计算的超时秒数，范围 `[3600, 259200]`；超时未完成转为 `expired` |

<Warning>
`callback_url` 在本平台**不受支持**，传入会返回 400。官方未将 Seedance 2.5 列入 `seed`、`frames`、`camera_fixed` 的支持模型，也不支持 `service_tier: flex`；请勿把这些字段用于 2.5 请求。
</Warning>

### 输出格式与任务类型参数

这两个参数仅适用于 **Seedance 2.5**，平台透传至上游；省略时不额外填值，由上游应用默认值。切换为 Seedance 2.0 或其他不支持的模型时应移除。

| 参数 | 类型 | 默认值 | 取值与作用 |
| --- | --- | --- | --- |
| `output_format` | string | `mp4` | `mp4` / `mov`，选择输出容器格式，详见[输出格式与编码](#输出格式与编码) |
| `omni_reference_task_type` | string | `auto` | `auto` / `reference` / `edit` / `extend`，仅用于全模态参考任务的子类型引导 |

`omni_reference_task_type` 只用于全模态参考，文生视频、首帧 / 首尾帧任务不需要设置。`auto` 由模型按素材和提示词判断任务类型；显式设置 `reference` / `edit` / `extend` 时，上游会在提交阶段提前校验对应参数，但实际意图与指定类型不一致时仍可能异步失败。

### content 数组

每个元素为一个内容项，`type` 决定其结构：

| type | 结构 | role 取值 | 说明 |
| --- | --- | --- | --- |
| `text` | `{"type":"text","text":"..."}` | — | 提示词。建议中文 ≤500 字、英文 ≤1000 词；台词放在双引号内可提升配音效果 |
| `image_url` | `{"type":"image_url","image_url":{"url":"..."},"role":"..."}` | `first_frame` / `last_frame` / `reference_image` | 支持公网 URL、Base64 data URI、`asset://素材ID` |
| `video_url` | `{"type":"video_url","video_url":{"url":"..."},"role":"reference_video"}` | `reference_video` | 公网 URL 或 `asset://素材ID`，不支持视频 Base64；最多 10 个，总时长 ≤30 秒；携带视频输入享受[计费折扣](/api-capabilities/seedance25/overview#模型定价) |
| `audio_url` | `{"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"}` | `reference_audio` | 公网 URL、Base64 data URI 或 `asset://素材ID`；WAV / MP3，单段 2–30 秒，最多 10 段，总时长 ≤30 秒；支持仅输入音频 |

### 素材要求

| 素材 | 格式 | 数量、时长及大小 |
| --- | --- | --- |
| 图片 | JPEG / PNG / WebP / BMP / TIFF / GIF / HEIC / HEIF | 首帧 1 张、首尾帧 2 张，或多模态参考最多 30 张；单张小于 30 MB |
| 视频 | MP4 / MOV，支持编码见下表 | 最多 10 个，总时长 ≤30 秒；非编辑任务单个 2–30 秒，编辑任务单个 4–30 秒；单个 ≤200 MB |
| 音频 | WAV / MP3 | 最多 10 段，单段 2–30 秒，总时长 ≤30 秒；单段 ≤15 MB |

- 图片和视频的宽高比均为 `[0.4, 2.5]`，宽、高均为 `[300, 6000]` 像素，均包含边界值。
- 输入视频支持 `480p` / `720p` / `1080p` / `4k`，总像素数（宽 × 高）须在 `[407696, 8295044]`，帧率为 `[24, 60]` FPS。**支持 4k 输入不代表支持 4k 输出**。
- 请求体不超过 64 MB；图片和音频可使用 Base64 data URI，大文件应使用 URL 或素材 ID；视频不支持 Base64。

**输入视频的容器与编码必须同时满足要求：**

| 容器 | 扩展名 | MIME | 视频编码 | 音频编码 |
| --- | --- | --- | --- | --- |
| MP4 | `.mp4` | `video/mp4` | H.264/AVC、H.265/HEVC | AAC、MP3 |
| QuickTime | `.mov` | `video/quicktime` | H.264/AVC、H.265/HEVC | AAC、MP3、PCM |

修改文件扩展名不会改变实际编码。**含真人人脸的图片或视频不能直接上传作为参考素材**；授权真人素材需先走 [素材库](/asset-management/asset-library) 与 [真人认证](/asset-management/real-person)，再以 `asset://` 引用。

### 生成模式

| 模式 | content 组合 |
| --- | --- |
| 文生视频 | 1 个 `text` |
| 首帧图生视频 | 可选 `text` + 1 个 `image_url`（role 可省略） |
| 首尾帧图生视频 | 可选 `text` + 2 个 `image_url`（role 必须分别为 `first_frame`、`last_frame`） |
| 多模态参考 | 可选 `text` + 0–30 张参考图 + 0–10 个参考视频 + 0–10 段参考音频（至少 1 个素材，允许仅音频） |

首帧、首尾帧、多模态参考是互斥场景：不能把 `first_frame` / `last_frame` 与参考图、参考视频或参考音频混用。多模态参考中可通过提示词描述首尾画面；如需严格约束首尾帧，应使用首尾帧模式。

### 任务类型与参数约束

| 任务类型 | 输入要求 | ratio | duration |
| --- | --- | --- | --- |
| 文生视频 | 文本提示词 | `adaptive` 或指定比例 | `-1` 或 4–30 秒整数 |
| 首帧 / 首尾帧图生视频 | 对应首帧 / 首尾帧图片 | 仅 `adaptive`，跟随首帧图片 | `-1` 或 4–30 秒整数 |
| 参考生成（`reference`） | 至少 1 个参考素材 | `adaptive` 或指定比例 | `-1` 或 4–30 秒整数 |
| 视频编辑（`edit`） | 至少 1 个 `reference_video`，单个 4–30 秒 | 仅 `adaptive`，跟随待编辑视频 | 仅 `-1`，跟随待编辑视频 |
| 视频延长（`extend`） | 至少 1 个 `reference_video`，单个 2–30 秒 | 仅 `adaptive`，跟随待延长视频 | `-1` 或 4–30 秒整数 |

<Warning>
平台转发 `omni_reference_task_type`、`ratio` 和 `duration`，不会因为选择了 `edit` / `extend` 就自动修正比例或时长。调用方界面选择编辑时，应锁定并提交 `ratio: adaptive`、`duration: -1`；选择延长时，只需锁定比例为 `adaptive`，时长仍可选择 `-1` 或 4–30 秒整数。不要把原视频的具体宽高比或秒数代替编辑任务要求的特殊值；不符合任务约束的参数由上游拒绝。
</Warning>

编辑任务的实际成片可能为非整数秒，可能比待编辑视频略短（官方说明误差约 0.4 秒）。提示词应明确说明生成新视频、编辑现有视频，或向前 / 向后延长，避免模型判定的任务类型与参数配置冲突。

例如，编辑一段 4–30 秒参考视频并输出 MOV，向创建任务接口提交以下 JSON：

```json 编辑视频并输出 MOV
{
  "model": "doubao-seedance-2-5-260628",
  "content": [
    {"type": "text", "text": "编辑视频1，将天空改为日落时分的暖色，保留原有主体动作和镜头"},
    {"type": "video_url", "video_url": {"url": "https://example.com/source.mov"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit",
  "output_format": "mov",
  "resolution": "1080p",
  "ratio": "adaptive",
  "duration": -1
}
```

延长视频时将任务类型改为 `extend`，在提示词中明确向前或向后延长；仍使用 `ratio: adaptive`，`duration` 可为 `-1` 或 4–30 秒整数。

## 输出格式与编码

通过 `output_format` 选择输出容器；这不是直接指定 H.264 / H.265 的编码参数。**显式请求 `mov` 时，平台保留上游原生规格产物**，容器、色度采样与音频编码保持不变。默认或显式请求 `mp4` 的任务按平台默认交付策略处理。

以下为**官方原始产物规格**；MP4 产物请以下载文件的实际媒体信息为准。

| 官方输出格式 | 用途与编码说明 |
| --- | --- |
| `mp4`（默认） | 常规播放与分发；官方分辨率说明中，2.5 的 1080p 输出采用 10bit 位深与 H.265/HEVC 编码 |
| `mov` | 调色、抠像、合成等专业后期；官方 MOV 专项说明为 H.264 视频编码 + yuv444p 色度采样 + PCM 音频编码，推荐用于视频编辑 / 延长的输入与输出 |

<Note>
官方分别列出了「1080p：10bit / H.265」和「MOV：H.264 / yuv444p / PCM」的说明，未在该接口文档中明确 `1080p + mov` 组合的位深与编码优先规则，因此不能把所有 MOV 都写成 H.265，也不能仅凭扩展名推断位深。需要特定规格时，请检查实际文件的媒体信息。
</Note>

输出帧率固定为 24fps，有声视频为单声道。H.265/HEVC 和 MOV 的 yuv444p / PCM 在部分浏览器或播放器中可能不兼容；官方列出的 MOV 兼容播放器包括 VLC、mpv、ffplay，以及 macOS 上的 IINA。

## 查询任务

`GET /api/v3/contents/generations/tasks/{task_id}`

任务状态机：`queued → running → succeeded / failed / cancelled / expired`。任务记录长期保留，可随时回查。

成功响应示例：

```json
{
  "id": "task_xxxx",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {
    "video_url": "https://api.looprouter.com/.../output.mp4?...",
    "last_frame_url": ""
  },
  "usage": {
    "completion_tokens": 493680,
    "total_tokens": 493680
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 10,
  "framespersecond": 24,
  "generate_audio": true,
  "output_format": "mp4",
  "created_at": 1752940800,
  "updated_at": 1752941120
}
```

<Warning>
成片地址在 `content.video_url` 字段，为**临时链接**。官方原始视频 URL 有效期为 24 小时，Seedance 2.5 视频 URL 下载次数上限为 100 次；平台转存链接的有效期以实际存储策略为准。请及时下载并转存，不要依赖重新查询来刷新过期链接；下载时**不要**携带 `Authorization` 头。
</Warning>

`output_format` 返回上游生成视频的格式（`mp4` / `mov`），单任务查询与任务列表均保留此字段。旧任务或上游未返回时会省略，请勿只凭下载 URL 的后缀判断格式。

查询返回的 `duration` 为整数秒约数，按「实际总帧数 ÷ 24，向下取整」计算，不保证等于文件的精确时长。例如 133 帧对应约 5.54 秒，接口返回 `duration: 5`。

<Info>
`usage.total_tokens` 为上游按「时长 × 分辨率像素 × 帧率」口径折算的视频 token 数，是结算依据。使用 `duration: -1` 或 `ratio: adaptive` 时，以响应中回填的实际值为准。
</Info>

## 任务列表与取消

本平台提供以下两个任务管理接口（列表参数与保留策略以本平台为准）：

**列出任务** — `GET /api/v3/contents/generations/tasks`

| 查询参数 | 说明 |
| --- | --- |
| `page_num` | 页码，默认 1 |
| `page_size` | 每页数量，默认 20，最大 500 |
| `filter.status` | 按状态过滤：`queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `filter.model` | 按模型过滤 |
| `filter.task_ids` | 按任务 ID 列表过滤 |

响应为 `{"items": [...], "total": n}`，元素结构与查询单个任务一致。

**取消/删除任务** — `DELETE /api/v3/contents/generations/tasks/{task_id}`

排队中的任务可以取消；`running` 状态的任务不可取消（返回 400 `invalid_task_status`）。成功返回 `{}`。

## 错误响应

所有错误采用与火山引擎一致的结构：

```json
{
  "error": {
    "code": "invalid_request",
    "message": "具体错误描述 (request id: ...)",
    "param": "",
    "type": "BadRequest"
  }
}
```

| HTTP 状态码 | type | 常见原因 |
| --- | --- | --- |
| 400 | `BadRequest` | 缺少 `model`/`content`；`resolution` 传入 `4k`（2.5 不支持）；`duration` 既非 `-1` 也非 4–30 秒整数；素材或任务参数不兼容；传了 `callback_url`；取消运行中任务 |
| 401 | `Unauthorized` | API Key 缺失或无效 |
| 403 | `Forbidden` | 令牌无权访问该模型；内容审核未通过（如真实人脸直传） |
| 404 | `NotFound` | 任务 ID 不存在或不属于当前账号 |
| 429 | `RateLimitExceeded` | 当前分组上游负载已饱和，请稍后再试 |
| 5xx | `InternalServerError` | 服务端异常，建议指数退避后重试 |

<Info>
429 与 5xx 建议采用指数退避重试（如 2s → 4s → 8s）。参数校验失败（400）与内容审核拒绝（403）**均不扣费**；已预扣的失败任务会自动退款。
</Info>

部分任务类型错误会在创建成功后异步返回。查询到 `status: failed` 时检查 `error.code`：`InvalidParameter.TaskTypeConstraint` 表示参数与模型判定的任务类型不兼容；官方显式任务类型与实际意图不一致时则为 `InvalidParameter.TaskTypeMismatch`。

## 核对依据

本页模型规格依据火山引擎官方 [创建视频生成任务](https://docs.volcengine.com/docs/82379/1520757)（2026-08-21 更新）与 [查询视频生成任务](https://docs.volcengine.com/docs/82379/1521309)（2026-08-19 更新）的文档快照核对；平台差异单独标明。

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/seedance25/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    从上传素材到角色一致性生成的完整链路
  </Card>
  <Card title="在线调试" icon="flask" href="/api-reference/create-video-task">
    在文档内直接试一试
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/wan3/overview.md

# 万相 3.0 能力总览

> 通义万相 3.0（wan3.0-video / wan3.0-video-prime）全能参考视频生成：模型介绍、技术规格、分辨率与宽高比、最长 30 秒时长、计费方式与常见问题；把 Base URL 指向网关、只换 API Key 即可调用

万相 3.0 是阿里通义万相系列的**全能参考视频生成模型（All-in-One）**，提供 `wan3.0-video` 与 `wan3.0-video-prime` 两个模型，**调用方式完全相同**，用同一个接口统一支持**文生视频**、**图生视频**（首帧 / 首尾帧）与**参考生视频**（参考图 / 参考视频 / 参考音频 / 文件 / 网页链接）。单次最长可生成 **30 秒**视频，输出帧率 **30fps**，并可选择是否携带音轨。LoopRouter 以与阿里百炼（DashScope）**完全一致的原生接口**对外提供该能力：接口路径、请求体、响应结构都与百炼官方相同，**你只需把 Base URL 从百炼域名换成网关地址、把 API Key 换成 LoopRouter 令牌，其余代码一行不改**。

<Note>
**换 Base URL 即可使用**：把原本指向 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 的请求改为 `https://api.looprouter.com` 即可——网关不需要 `WorkspaceId` 子域，也不需要百炼 API Key，统一用 LoopRouter 的 `sk-` 令牌鉴权。已有的百炼官方示例、SDK 或自研代码无需改动请求结构。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/wan3/video-generation">
    完整参数、四种生成模式、media 数组、响应结构与错误码
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频任务
  </Card>
  <Card title="计费与分组" icon="receipt" href="/user-groups">
    分辨率档位单价与分组倍率说明
  </Card>
  <Card title="AI 集成指南" icon="robot" href="/ai-usage">
    把文档直接交给 ChatGPT / Claude 接入
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="一个接口四种模式" icon="layer-group">
    文生 / 首帧图生 / 首尾帧图生 / 参考生视频，共用同一端点，仅靠 `input.media` 组合区分
  </Card>
  <Card title="全能参考生视频" icon="wand-magic-sparkles">
    参考图 ≤10、参考视频 ≤5、参考音频 ≤5，还可传文件或网页链接，`prompt` 中用「图1」「视频1」指代素材
  </Card>
  <Card title="更长单段时长" icon="clock">
    时长范围 2–30 秒，一次生成覆盖更完整的镜头叙事
  </Card>
  <Card title="音画同步" icon="volume-high">
    `audio` 默认开启，输出视频自带声音；开关声音价格相同
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `wan3.0-video` | 全能参考视频生成标准版，支持全部生成模式，时长最长 30 秒，输出分辨率 480P / 720P / 1080P，帧率 30fps |
| `wan3.0-video-prime` | 全能参考视频生成加强版，调用方式与 `wan3.0-video` 完全一致，接口、请求体、参数、响应结构均相同 |

<Note>
两个模型**调用方式完全相同**，只需切换请求体里的 `model` 字段值即可；实际可用模型与定价以控制台「模型广场」为准，无需关心上游版本后缀或接入点 ID。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 首帧图生 / 首尾帧图生 / 参考生视频 |
| 分辨率 | `480P` / `720P` / `1080P`（默认 `1080P`；传入其他档位返回错误且不扣费） |
| 宽高比 | `adaptive`（默认，跟随输入素材）、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`（**不支持 `21:9`**） |
| 时长 | **2–30 秒**整数；有视频输入时「输入视频总时长 + 输出时长 ≤ 30 秒」 |
| 帧率 | 固定 30fps |
| 音频 | `audio` 默认 `true`，输出视频含声音；`false` 则无音轨（价格相同） |
| 参考素材 | 参考图 ≤10 张 + 参考视频 ≤5 段（合计 ≤15 秒）+ 参考音频 ≤5 段（合计 ≤15 秒）；或文件 ≤1、网页链接 ≤1 |
| 图片要求 | JPEG/JPG/PNG（不支持透明通道）/BMP/WEBP；单边 [240, 8000]px；长宽比 ≤8:1；小于 20MB |
| 提示词建议 | 支持中英文，≤20000 字符，超出自动截断；台词可用双引号包裹 |
| 任务模式 | 异步任务：`PENDING → RUNNING → SUCCEEDED / FAILED / CANCELED` |
| 成片链接 | `output.video_url` 为临时链接，请在获取后尽快转存 |

<Tip>
`first_frame` / `last_frame`（首帧、尾帧）与 `reference_image` / `reference_video` / `reference_audio` / `file` / `link`（参考类）**互斥**，不能在同一请求中混用。
</Tip>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v1/services/aigc/video-generation/video-synthesis` | 创建视频生成任务 |
| GET | `/api/v1/tasks/{task_id}` | 根据任务 ID 查询结果 |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。`X-DashScope-Async` 头可选，值为 `enabled`。
</Tip>

<Warning>
**与百炼官方的两点取值差异，接入前请留意：**

1. **网关地址不带 `WorkspaceId`**：直接用 `https://api.looprouter.com`，不需要业务空间 ID 子域。
2. **不支持智能时长 `duration: -1`**：请传 2–30 秒的明确整数。提交时长未知会导致按秒计费无法预扣，故网关直接返回参数错误。
</Warning>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程，与 Seedance 2.5 / 可灵 3.0 同一「按秒 × 按分辨率档」机制：

<Steps>
  <Step title="提交预扣">
    任务创建成功后，按请求的分辨率档位与时长预估并预扣一笔额度，日志中心产生一条预扣记录。分辨率越高、时长越长，预扣越多。
  </Step>
  <Step title="完成结算">
    任务成功后按实际输出时长（向上取整到整秒）结算，多退少补；任务失败则全额退回预扣。
  </Step>
</Steps>

按秒计费，单价按分辨率档位区分：分辨率越高单价越高，`1080P`（默认）> `720P` > `480P`。**具体单价以控制台「模型广场」展示为准。**

<Info>
**计费规则**：时长向上取整到整秒，最短按 1 秒、最长按 30 秒计。开关音频（`audio`）不影响价格。

**不扣费场景**：参数校验失败、鉴权失败、内容审核拒绝均不产生费用；已预扣的失败任务会自动退款。
</Info>

实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率（具体折扣以商务对接约定为准），分组同时决定可用的分辨率档位。

## 限流与重试

- 平台按渠道维度做 RPM 智能调度：并发高峰时任务会短暂排队而不是直接失败。
- 收到 429（`Throttling`，当前分组上游负载已饱和）或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔 15 秒；时长越长生成耗时越久，长视频请适当延长轮询周期与超时时间。

## 常见问题

<AccordionGroup>
  <Accordion title="怎么从百炼官方迁移到网关？">
    把请求域名从 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com` 换成 `https://api.looprouter.com`，把 `Authorization` 里的百炼 API Key 换成 LoopRouter 的 `sk-` 令牌即可。路径 `/api/v1/services/aigc/video-generation/video-synthesis` 与 `/api/v1/tasks/{task_id}`、请求体与响应结构都保持不变，无需业务空间 ID。
  </Accordion>
  <Accordion title="为什么创建任务只返回 task_id，没有视频？">
    这是异步任务接口：创建仅入队并返回 `output.task_id`，需轮询 `GET /api/v1/tasks/{task_id}` 直到 `task_status` 变为 `SUCCEEDED`，再从 `output.video_url` 下载成片。
  </Accordion>
  <Accordion title="成功状态是什么？">
    是 `SUCCEEDED`（全大写）。终态请匹配 `SUCCEEDED / FAILED / CANCELED`；`UNKNOWN` 表示任务不存在或已过查询有效期。
  </Accordion>
  <Accordion title="支持哪些分辨率？为什么不能用 4K？">
    万相 3.0 支持 `480P` / `720P` / `1080P` 三档，默认 `1080P`。官方未提供更高档位，传入其他值会返回参数错误且不扣费。
  </Accordion>
  <Accordion title="能用智能时长（duration = -1）吗？">
    网关**不支持** `-1`。因为提交时真实时长未知，无法按秒预扣，会导致少收费。请传 2–30 秒的明确整数；有视频输入时确保「输入 + 输出 ≤ 30 秒」。
  </Accordion>
  <Accordion title="reference_xx 和 first_frame 能一起传吗？">
    不能。`first_frame` / `last_frame` 与 `reference_image` / `reference_video` / `reference_audio` / `file` / `link` 互斥，混用会返回 `The two modes are mutually exclusive` 错误。
  </Accordion>
  <Accordion title="视频链接过期了怎么办？">
    `output.video_url` 是临时链接，任务成功后请尽快下载并转存到自己的存储；过期后可重新调用查询接口获取新链接，但任务本身也有保留期限。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/wan3/video-generation">
    参数、media 数组与响应详解
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
  <Card title="AI 集成指南" icon="robot" href="/ai-usage">
    llms.txt 与推荐提示词
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/wan3/video-generation.md

# 万相 3.0 视频生成 API

> 任务式异步接口：文生视频、图生视频、参考生视频；与阿里百炼（DashScope）原生格式完全一致，把 Base URL 指向网关、只换 API Key 即可调用

万相 3.0（`wan3.0-video` 与 `wan3.0-video-prime`，**两个模型调用方式完全相同**，仅需切换请求体里的 `model` 字段）视频生成采用**异步任务**模式：先提交任务拿到 `task_id`，再轮询查询接口获取成片。接口路径、请求体、响应结构与阿里百炼（DashScope）原生完全一致——**你只需把 Base URL 从百炼域名换成 `https://api.looprouter.com`、把 API Key 换成 LoopRouter 的 `sk-` 令牌，已有的百炼官方示例、SDK 或自研代码即可直接运行**，无需业务空间 ID（`WorkspaceId`）。

<Tip>
文生、图生、参考生视频共用同一个接口，仅靠 `input.media` 数组的组合区分模式。`wan3.0-video` 与 `wan3.0-video-prime` 的请求体、参数、响应结构完全一致，切换模型只改 `model` 字段。模型清单、定价与常见问题见 [能力总览](/api-capabilities/wan3/overview)。
</Tip>

<Warning>
`ratio` 仅支持 `adaptive` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`，两个模型均**不支持 `21:9`**，传入会返回参数错误。
</Warning>

<Warning>
**接入前请注意以下差异点，可以避开绝大多数排障时间：**

1. Base URL 为 `https://api.looprouter.com`，完整路径是 `/api/v1/services/aigc/video-generation/video-synthesis`，**不需要** `{WorkspaceId}` 子域。
2. 鉴权用 LoopRouter 的 `sk-` 令牌（`Authorization: Bearer sk-...`），不是百炼 API Key。
3. `X-DashScope-Async` 请求头可选，值为 `enabled`。
4. `resolution` 支持 `480P` / `720P` / `1080P`（默认 `1080P`）；传入其他档位返回错误且不扣费。
5. `duration` 传 **2–30** 的明确整数；网关**不支持**智能时长 `-1`。有视频输入时「输入视频总时长 + 输出时长 ≤ 30 秒」。
6. 成功状态是 `SUCCEEDED`（全大写）；成片 `output.video_url` 为临时链接，请尽快转存。
</Warning>

## 代码示例

<CodeGroup>

```bash 创建任务（cURL）
curl --location "https://api.looprouter.com/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "X-DashScope-Async: enabled" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "一只小猫在月光下的屋顶上奔跑，城市的霓虹灯在远处闪烁，电影级画质，流畅运镜。"
    },
    "parameters": {
      "resolution": "1080P",
      "ratio": "adaptive",
      "duration": 5,
      "prompt_extend": true
    }
  }'

# 返回：{"output":{"task_status":"PENDING","task_id":"..."},"request_id":"..."}
# 只返回任务 ID，视频需轮询查询接口获取
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {
    "Authorization": "Bearer sk-你的APIKey",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enabled",  # 可选
}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/api/v1/services/aigc/video-generation/video-synthesis",
    headers=HEADERS,
    json={
        "model": "wan3.0-video",
        "input": {
            "prompt": "一只小猫在月光下的屋顶上奔跑，城市的霓虹灯在远处闪烁，电影级画质，流畅运镜。"
        },
        "parameters": {
            "resolution": "1080P",
            "ratio": "adaptive",
            "duration": 5,          # 2~30 秒的明确整数，不支持 -1
            "prompt_extend": True,   # 开启 prompt 智能改写，短提示词效果提升明显
            # "audio": True,         # 默认输出含声音
            # "seed": 42,            # 固定随机种子，结果更可复现
        },
    },
)
resp.raise_for_status()
task_id = resp.json()["output"]["task_id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 15 秒一次；长时长任务可适当延长）
while True:
    task = requests.get(
        f"{BASE}/api/v1/tasks/{task_id}",
        headers={"Authorization": HEADERS["Authorization"]},
    ).json()
    status = task["output"]["task_status"]
    print("当前状态:", status)
    if status in ("SUCCEEDED", "FAILED", "CANCELED", "UNKNOWN"):
        break
    time.sleep(15)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "SUCCEEDED":
    video_url = task["output"]["video_url"]
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open("output.mp4", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
else:
    print("任务未成功:", task["output"].get("message"))
```

```python 图生 / 首尾帧 / 参考生视频（Python）
# 模式二：首帧图生视频 —— 用 first_frame 严格指定视频第一帧
first_frame_body = {
    "model": "wan3.0-video",
    "input": {
        "prompt": "镜头缓缓推进，人物转身微笑，背景光线由冷转暖。",
        "media": [
            {"type": "first_frame", "url": "https://example.com/first.png"}
        ],
    },
    "parameters": {"resolution": "1080P", "ratio": "adaptive", "duration": 5},
}

# 模式三：首尾帧图生视频 —— 同时约束首帧与尾帧
first_last_frame_body = {
    "model": "wan3.0-video",
    "input": {
        "prompt": "一个年轻女孩从微笑逐渐变为大笑，镜头缓缓推进。",
        "media": [
            {"type": "first_frame", "url": "https://example.com/first.png"},
            {"type": "last_frame", "url": "https://example.com/last.jpg"},
        ],
    },
    "parameters": {"resolution": "1080P", "ratio": "adaptive", "duration": 5},
}

# 模式四：全能参考生视频 —— 参考图/参考视频/参考音频自由组合，
# prompt 中可用「图1」「视频1」按 media 数组顺序指代（图与视频分别计数）
reference_body = {
    "model": "wan3.0-video",
    "input": {
        "prompt": "视频1抱着图1，在图2的椅子上弹奏一支舒缓的乡村民谣。",
        "media": [
            {"type": "reference_video", "url": "https://example.com/role.mp4"},
            {"type": "reference_image", "url": "https://example.com/object1.png"},
            {"type": "reference_image", "url": "https://example.com/chair2.png"},
            # {"type": "reference_audio", "url": "https://example.com/voice.mp3"},
        ],
    },
    "parameters": {"resolution": "480P", "ratio": "adaptive", "duration": 5, "prompt_extend": True},
}
```

```javascript Node.js
const BASE = "https://api.looprouter.com";
const KEY = process.env.LOOPROUTER_API_KEY;

async function main() {
  // 创建任务
  const createRes = await fetch(
    `${BASE}/api/v1/services/aigc/video-generation/video-synthesis`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-DashScope-Async": "enabled",
        Authorization: `Bearer ${KEY}`,
      },
      body: JSON.stringify({
        model: "wan3.0-video",
        input: {
          prompt: "一只小猫在月光下的屋顶上奔跑，城市的霓虹灯在远处闪烁。",
        },
        parameters: { resolution: "1080P", ratio: "adaptive", duration: 5 },
      }),
    }
  );
  const taskId = (await createRes.json()).output.task_id;
  console.log("任务已创建:", taskId);

  // 轮询
  for (;;) {
    await new Promise((r) => setTimeout(r, 15000));
    const task = await (
      await fetch(`${BASE}/api/v1/tasks/${taskId}`, {
        headers: { Authorization: `Bearer ${KEY}` },
      })
    ).json();
    const status = task.output.task_status;
    console.log("当前状态:", status);
    if (["SUCCEEDED", "FAILED", "CANCELED", "UNKNOWN"].includes(status)) {
      if (status === "SUCCEEDED") console.log("视频地址:", task.output.video_url);
      else console.error("任务未成功:", task.output.message);
      break;
    }
  }
}

main();
```

```bash 查询任务（cURL）
curl -X GET "https://api.looprouter.com/api/v1/tasks/{task_id}" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

</CodeGroup>

## 请求参数速查

`POST /api/v1/services/aigc/video-generation/video-synthesis`，请求头 `Authorization: Bearer sk-...`、`Content-Type: application/json`；`X-DashScope-Async` 可选，值为 `enabled`。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | `wan3.0-video` 或 `wan3.0-video-prime`（两者调用方式相同），可用模型以控制台「模型广场」为准 |
| `input` | object | 是 | — | 输入信息；`prompt` 与 `media` 至少填其一 |
| `input.prompt` | string | 条件必填 | — | 文本提示词，支持中英文，≤20000 字符；参考模式下可用「图1」「视频1」指代 `media` 素材 |
| `input.media` | array | 条件必填 | — | 媒体素材数组，见下方 [media 数组](#media-数组) |
| `parameters` | object | 否 | — | 视频处理参数 |
| `parameters.resolution` | string | 否 | `1080P` | `480P` / `720P` / `1080P`；传入其他档位返回错误且不扣费 |
| `parameters.ratio` | string | 否 | `adaptive` | `adaptive`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；**不支持 `21:9`** |
| `parameters.duration` | int | 否 | `5` | 输出时长（秒），范围 **2–30**；有视频输入时「输入 + 输出 ≤ 30」。**不支持 `-1`** |
| `parameters.audio` | bool | 否 | `true` | 输出视频是否含音轨；开关声音价格相同 |
| `parameters.prompt_extend` | bool | 否 | `true` | 是否开启 prompt 智能改写，短提示词效果提升明显但略增耗时 |
| `parameters.seed` | int | 否 | — | 随机种子，用于复现结果，取值 [0, 2147483647] |
| `parameters.watermark` | bool | 否 | `false` | 是否添加水印标识 |

<Warning>
网关**不支持**智能时长 `duration: -1`（提交时真实时长未知，无法按秒预扣，会返回参数错误）。请传 2–30 秒的明确整数。
</Warning>

### media 数组

`input.media` 的每个元素为一个媒体对象，含 `type` 与 `url` 两个字段：

| type | 数量上限 | 说明 |
| --- | --- | --- |
| `first_frame` | 1 | 首帧图像，严格作为视频第一帧 |
| `last_frame` | 1 | 尾帧图像，严格作为视频最后一帧 |
| `reference_image` | 10 | 参考图像。数组中第 1 个对应「图1」，第 2 个对应「图2」，以此类推 |
| `reference_video` | 5 | 参考视频，合计时长 ≤15 秒。第 1 个对应「视频1」，依次类推（图与视频分别计数） |
| `reference_audio` | 5 | 参考音频，合计时长 ≤15 秒 |
| `file` | 1 | 文件（docx/pdf/pptx/xlsx 等，≤50 页、≤100MB）；不可与 `link` 同传 |
| `link` | 1 | 公开网页链接（无需登录的新闻/博客等）；不可与 `file` 同传 |

`url` 支持三种形式：**公网 URL**（HTTP/HTTPS）、**OSS 临时 URL**（`oss://...`）、**Base64 编码**（`data:{MIME_type};base64,{data}`）。

图像要求：JPEG/JPG/PNG（不支持透明通道）/BMP/WEBP，单边 [240, 8000]px，长宽比 ≤8:1，小于 20MB。视频要求：mp4/mov，单段 [1, 15] 秒，单边 [240, 4096]px，单文件 ≤100MB。音频要求：wav/mp3，单段 [1, 15] 秒，≤15MB。

<Warning>
`first_frame` / `last_frame` 与 `reference_image` / `reference_video` / `reference_audio` / `file` / `link` **互斥**，不能在同一请求中混用，否则返回 `The two modes are mutually exclusive` 错误。
</Warning>

### 生成模式

| 模式 | media 组合 |
| --- | --- |
| 文生视频 | 仅 `input.prompt`，不传 `media` |
| 首帧图生视频 | `prompt` + 1 个 `first_frame` |
| 首尾帧图生视频 | `prompt` + 1 个 `first_frame` + 1 个 `last_frame` |
| 参考生视频 | `prompt` + 参考图 / 参考视频 / 参考音频（可组合），或 `file` / `link` |

## 查询任务

`GET /api/v1/tasks/{task_id}`

任务状态机：`PENDING → RUNNING → SUCCEEDED / FAILED / CANCELED`；`UNKNOWN` 表示任务不存在或已过查询有效期。

成功响应示例（与百炼原生结构一致）：

```json
{
  "request_id": "78c9b768-0285-996c-b682-xxxxxx",
  "output": {
    "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2026-08-06 10:01:35.452",
    "scheduled_time": "2026-08-06 10:01:35.507",
    "end_time": "2026-08-06 10:13:33.838",
    "orig_prompt": "一只小猫在月光下的屋顶上奔跑……",
    "video_url": "https://.../output.mp4"
  },
  "usage": {
    "video_count": 1,
    "duration": 5.0,
    "input_video_duration": 0.0,
    "output_video_duration": 5.0,
    "fps": 30,
    "SR": 1080,
    "ratio": "16:9"
  }
}
```

<Warning>
成片地址在 `output.video_url` 字段，为**临时链接**，请及时转存；下载时请求中**不要**携带 `Authorization` 头。
</Warning>

<Info>
`usage` 为成功任务的用量统计：`output_video_duration` 是实际输出时长（结算依据，向上取整到整秒计费），`SR` 为输出分辨率，`fps` 固定 30。
</Info>

## 错误响应

错误采用与百炼一致的结构 `{code, message, request_id}`：

```json
{
  "code": "InvalidApiKey",
  "message": "No API-key provided. (request id: ...)",
  "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}
```

任务执行阶段的失败会在查询响应的 `output` 中回填 `code` / `message`，并把 `task_status` 置为 `FAILED`：

```json
{
  "request_id": "e5e57877-c0fc-47ed-8fad-xxxxxx",
  "output": {
    "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
    "task_status": "FAILED",
    "code": "InvalidParameter",
    "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
  }
}
```

| HTTP 状态码 | code | 常见原因 |
| --- | --- | --- |
| 400 | `InvalidParameter` | 缺少 `model`/`input`；`resolution` 非 480P/720P/1080P；`duration` 超出 2–30 或传了 `-1`；首帧与参考类混用 |
| 401 | `InvalidApiKey` | API Key 缺失或无效 |
| 403 | `AccessDenied` | 令牌无权访问该模型；内容审核未通过 |
| 429 | `Throttling` | 当前分组上游负载已饱和，请稍后再试 |
| 5xx | `InternalError` | 服务端异常，建议指数退避后重试 |

<Info>
429 与 5xx 建议采用指数退避重试（如 2s → 4s → 8s）。参数校验失败、鉴权失败与内容审核拒绝**均不扣费**；已预扣的失败任务会自动退款。
</Info>

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/wan3/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
  <Card title="AI 集成指南" icon="robot" href="/ai-usage">
    llms.txt 与推荐提示词
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/minimax/overview.md

# MiniMax-H3 能力总览

> MiniMax-H3（海螺 Hailuo）多模态视频模型：原生 /v2 接口、生成模式、技术规格、提示增强、视频再生与计费说明

MiniMax-H3（海螺 Hailuo-03）是 MiniMax 的多模态视频生成模型，能同时理解文本、图片、视频与音频输入，支持文生视频、图生视频、首尾帧、多模态参考生成，并提供**提示增强（Context-IR）**与**视频再生（768P → 2K）**两项进阶能力。LoopRouter 以**与 MiniMax 官方完全一致的原生 `/v2` 接口**对外透传：官方示例代码只需把 Base URL 换成 `https://api.looprouter.com`、把 `Authorization` 换成 LoopRouter 令牌即可运行。

<Note>
本接口族的路径、请求体与响应体与 MiniMax 官方保持一致（`/v2/video_generation` 等，**没有** `/api` 前缀）。与豆包 Seedance 的 `/api/v3/...` 接口是两套独立的 API，不要混用。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/minimax/video-generation">
    创建 / 查询 / 列表 / 删除，以及提示增强与视频再生
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/minimax/create-video-task">
    在文档内直接对 `/v2` 接口发起真实请求
  </Card>
  <Card title="获取 API Key" icon="key" href="https://console.looprouter.com/keys">
    在控制台创建 `sk-` 令牌
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="多模态输入" icon="layer-group">
    文本、图片、视频、音频自由组合，支持首尾帧与参考生成
  </Card>
  <Card title="提示增强 Context-IR" icon="wand-magic-sparkles">
    `/v2/h3_context_ir` 理解多模态上下文，输出结构化增强提示词
  </Card>
  <Card title="视频再生 2K" icon="arrow-up-right-dots">
    `/v2/video_regeneration` 将 768P 成片重生成为 2K 高清
  </Card>
  <Card title="原生接口透传" icon="plug">
    请求 / 响应字节形状镜像官方，迁移零改造
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 |
| --- | --- |
| `MiniMax-H3` | 多模态视频模型，覆盖生成、提示增强、视频再生三类任务（靠端点区分，`model` 恒为 `MiniMax-H3`） |

<Note>
三类任务（`video_generation` / `h3_context_ir` / `video_regeneration`）在请求体中 `model` 均填 `MiniMax-H3`，任务类型由**调用的端点**决定，响应里的 `task_type` 会回显 `generation` / `h3_context_ir` / `regeneration`。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 图生视频（首帧、尾帧、首尾帧）/ 多模态参考 |
| 分辨率 | `768P` / `2K` |
| 时长 | `4`–`15` 秒整数 |
| 宽高比 | `adaptive`（默认）、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| 提示词 | 必填一条非空 `text`，最长 7000 字符 |
| 参考图片 | JPG/JPEG/PNG/WEBP/HEIC/HEIF；单张 ≤30MB；边长 [256, 5760]px；宽高比 [0.4, 2.5]；首帧 ≤1、尾帧 ≤1、参考图 ≤9 |
| 参考视频 | MP4/MOV（视频 H.264/HEVC，音频 AAC/MP3）；单个 ≤50MB；≤3 段，单段 2–15 秒且合计 ≤15 秒 |
| 参考音频 | WAV/MP3；单个 ≤15MB；≤3 段，单段 2–15 秒且合计 ≤15 秒 |
| 请求体大小 | 整体 ≤64MB，大文件请用公网 URL |
| 任务模式 | 异步任务：`queued → running → succeeded / failed / cancelled` |
| 任务保留 | 仅可查询近 **7 天**内的任务；成片 URL 为限时链接，请及时转存 |

<Warning>
图生视频（首帧/尾帧）与多模态参考**互斥**：同一请求不能同时出现 `first_frame`/`last_frame` 与任意 `reference_*` 角色。
</Warning>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/v2/video_generation` | 创建视频生成任务 |
| GET | `/v2/query/video_generation/{task_id}` | 查询单个任务 |
| GET | `/v2/query/video_generation` | 任务列表（分页/筛选） |
| DELETE | `/v2/video_generation/{task_id}` | 取消/删除任务 |
| POST | `/v2/h3_context_ir` | 提示增强（返回增强提示词，不生成视频） |
| POST | `/v2/video_regeneration` | 视频再生（768P → 2K） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。
</Tip>

## 模型定价

计费采用**提交预扣、完成结算**的两段式流程，不同任务类型口径不同：

| 任务类型 | 计费口径 |
| --- | --- |
| 视频生成 / 视频再生 | 按**分辨率 × 时长（秒）**计费，`768P` 与 `2K` 各有每秒单价；视频再生固定按 `2K` 结算 |
| 提示增强 Context-IR | 按 **token** 计费（`prompt_tokens` 输入 + `completion_tokens` 输出，分别核价） |

<Steps>
  <Step title="提交预扣">
    任务创建成功后按参数（分辨率、时长）预估并预扣一笔额度。视频再生无 `duration`，按最大可计费时长预扣。
  </Step>
  <Step title="完成结算">
    任务成功后按响应 `usage` 的实际用量结算（视频看 `output_seconds`，Context-IR 看 token），多退少补；任务失败或被取消全额退回。
  </Step>
</Steps>

<Info>
`768P` / `2K` 每秒单价与 Context-IR 每百万 token 单价请以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率。
</Info>

## 限流与重试

- 收到 429（`rate_limit_error`）或 5xx（`server_error`）时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔约 10 秒；`2K` 与长时长任务生成耗时更久，请适当延长轮询周期。

## 常见问题

<AccordionGroup>
  <Accordion title="它和豆包 Seedance 是同一个接口吗？">
    不是。MiniMax-H3 走原生 `/v2/...` 接口（无 `/api` 前缀），豆包 Seedance 走 `/api/v3/contents/generations/tasks`。请求体与响应体结构也不同，按各自文档接入。
  </Accordion>
  <Accordion title="创建任务后怎么拿到视频？">
    这是异步任务：创建返回 `task_id`，需轮询 `GET /v2/query/video_generation/{task_id}` 直到 `status` 为 `succeeded`，再从 `task.content.url` 下载成片。
  </Accordion>
  <Accordion title="支持哪些分辨率？">
    仅 `768P` 与 `2K` 两档。视频再生（regeneration）的输出恒为 `2K`。
  </Accordion>
  <Accordion title="为什么查询旧任务返回 invalid task_id？">
    任务与查询窗口仅覆盖近 7 天，超过 7 天的任务 ID 无法再查询。请在生成后尽快转存成片。
  </Accordion>
  <Accordion title="Context-IR 为什么没有视频？">
    `/v2/h3_context_ir` 只做提示增强：成功后 `task.content.prompt` 返回结构化增强提示词，`modality` 为 `text`，不产出视频。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/minimax/video-generation">
    参数、示例、查询、列表、删除、提示增强与视频再生
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/minimax/video-generation.md

# MiniMax-H3 视频生成 API

> 原生 /v2 任务接口：创建、查询、列表、删除，以及提示增强（Context-IR）与视频再生（Regeneration）

MiniMax-H3 采用**异步任务**模式，接口与 MiniMax 官方 `/v2` 完全一致：先提交任务拿到 `task_id`，再轮询查询接口获取成片。已有的官方示例代码只需替换 Base URL 与 `Authorization` 即可运行。

<Warning>
**接入前请注意以下要点：**

1. Base URL 为 `https://api.looprouter.com`，端点是 `/v2/video_generation` 等，**没有** `/api` 前缀。
2. 鉴权用 LoopRouter 令牌：`Authorization: Bearer sk-...`（不是 MiniMax 官方的 JWT）。
3. `resolution` 只有 `768P` 与 `2K` 两档；`duration` 为 `4`–`15` 秒整数。
4. 成功状态是 `succeeded`；成片 `task.content.url` 为限时链接，且任务仅可查询近 **7 天**，请尽快转存。
5. 文生视频（t2v）时 `ratio` **必填且不能是 `adaptive`**；图生视频（i2v）时比例由输入图决定、`ratio` 恒按 `adaptive` 处理。
</Warning>

## 创建视频任务

`POST /v2/video_generation`

<CodeGroup>

```bash 文生视频（cURL）
curl -X POST "https://api.looprouter.com/v2/video_generation" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "一个男孩在海边打篮球" }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

# 返回：{"task_id": "424010985738629"}
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {"Authorization": "Bearer sk-你的APIKey"}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/v2/video_generation",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [
            {"type": "text", "text": "一个男孩在海边打篮球"}
        ],
        "resolution": "2K",
        "duration": 5,
        "ratio": "16:9",
    },
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 10 秒一次）
while True:
    task = requests.get(
        f"{BASE}/v2/query/video_generation/{task_id}",
        headers=HEADERS,
    ).json()["task"]
    status = task["status"]
    print("当前状态:", status)
    if status in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(10)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "succeeded":
    video_url = task["content"]["url"]
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open("output.mp4", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
else:
    print("任务未成功:", task.get("error"))
```

```python 图生视频与多模态参考（Python）
# 首帧图生视频：text + 1 张 first_frame 图（ratio 恒按 adaptive）
i2v_body = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "镜头缓缓推进，人物转身微笑"},
        {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive",
}

# 多模态参考：text + 参考视频 + 参考音频（不能与 first_frame/last_frame 混用）
r2v_body = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "参考该片段的运镜与配乐节奏，生成新的城市夜景"},
        {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"},
        {"type": "audio_url", "audio_url": {"url": "https://example.com/voice.mp3"}, "role": "reference_audio"},
    ],
    "resolution": "2K",
    "duration": 6,
    "ratio": "adaptive",
}
```

```bash 查询任务（cURL）
curl "https://api.looprouter.com/v2/query/video_generation/424010985738629" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

</CodeGroup>

### 请求参数速查

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 固定 `MiniMax-H3` |
| `content` | array | 是 | — | 多模态输入数组，见下方[内容项说明](#content-数组) |
| `resolution` | string | 是 | — | `768P` / `2K` |
| `duration` | int | 是 | — | 输出时长（秒），`4`–`15` |
| `ratio` | string | 条件 | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；t2v 必填且不能为 `adaptive` |
| `aigc_watermark` | bool | 否 | `false` | 是否叠加 AIGC 水印 |
| `callback_url` | string | 否 | — | 任务状态变化的回调地址 |

### content 数组

每个元素是一个内容项，`type` 决定其结构，可选 `role` 指定用途：

| type | 结构 | role 取值 | 说明 |
| --- | --- | --- | --- |
| `text` | `{"type":"text","text":"..."}` | — | 提示词，**必填一条非空文本**，最长 7000 字符 |
| `image_url` | `{"type":"image_url","image_url":{"url":"..."},"role":"..."}` | `first_frame` / `last_frame` / `reference_image` | 首帧/尾帧或参考图 |
| `video_url` | `{"type":"video_url","video_url":{"url":"..."},"role":"reference_video"}` | `reference_video` | 参考视频（仅参考用途） |
| `audio_url` | `{"type":"audio_url","audio_url":{"url":"..."},"role":"reference_audio"}` | `reference_audio` | 参考音频（仅参考用途） |

**URL 支持三种形式**：公网 URL、Base64 data URI（`data:image/...`、`data:video/mp4;...`、`data:audio/...`），或已上传至 MiniMax 文件接口的 `mm_file://{file_id}`。大文件建议用公网 URL（请求体整体 ≤64MB）。

素材数量与格式限制见 [能力总览 → 技术规格](/api-capabilities/minimax/overview#技术规格)。

### 生成模式

| 模式 | content 组合 | ratio |
| --- | --- | --- |
| 文生视频（t2v） | 1 个 `text` | 必填，不能为 `adaptive` |
| 首帧图生视频（i2v） | `text` + 1 张图（`first_frame` 或不标 role） | 恒按 `adaptive` |
| 尾帧图生视频 | `text` + 1 张 `last_frame` 图 | 恒按 `adaptive` |
| 首尾帧 | `text` + `first_frame` + `last_frame` 各 1 张 | 恒按 `adaptive` |
| 多模态参考（r2v） | `text` + `reference_image` / `reference_video` / `reference_audio` | 可选，默认 `adaptive` |

<Warning>
图生视频（`first_frame`/`last_frame`）与多模态参考（`reference_*`）**互斥**，不能在同一请求中混用。
</Warning>

## 查询任务

`GET /v2/query/video_generation/{task_id}`

任务状态机：`queued → running → succeeded / failed / cancelled`。仅可查询近 **7 天**内的任务。

响应根对象包含一个 `task` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 任务 ID |
| `model` | string | 模型名，`MiniMax-H3` |
| `status` | string | `queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `error` | object | 仅失败时返回，含 `code`、`message` |
| `created_at` / `updated_at` | int | Unix 时间戳（秒） |
| `content` | object | 输出：`url`（成片限时下载地址）或 `prompt`（Context-IR 增强提示词） |
| `resolution` | string | 输出分辨率 |
| `duration` | int | 输出时长（秒） |
| `usage` | object | 计费用量（见下） |
| `ratio` | string | 宽高比，不适用时可能为空串 |
| `task_type` | string | `generation` / `h3_context_ir` / `regeneration` |
| `modality` | string | `video` / `text` |

`usage` 字段：

| 字段 | 说明 |
| --- | --- |
| `total_seconds` | 总计费秒数（输入 + 输出） |
| `input_seconds` | 输入参考视频计费秒数 |
| `output_seconds` | 输出视频计费秒数 |
| `input_image_count` | 计费图片数 |
| `total_tokens` / `prompt_tokens` / `completion_tokens` | Context-IR 的 token 用量 |

成功响应示例：

```json
{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://api.looprouter.com/.../output.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

失败响应示例：

```json
{
  "task": {
    "id": "424010985738630",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "created_at": 1785125529,
    "updated_at": 1785125700,
    "resolution": "2K",
    "duration": 5,
    "usage": { "total_seconds": 0, "input_seconds": 0, "output_seconds": 0, "input_image_count": 0 },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

<Warning>
`task.content.url` 为**限时下载链接**，请及时转存；下载时请求中**不要**携带 `Authorization` 头。
</Warning>

## 任务列表

`GET /v2/query/video_generation`

分页查询近 7 天的任务，可按状态、任务 ID、模型、任务类型筛选。全部为可选查询参数：

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `page_num` | int | `1` | 页码，从 1 开始 |
| `page_size` | int | `20` | 每页数量 |
| `filter.status` | string | — | `queued` / `running` / `succeeded` / `failed` / `cancelled` |
| `filter.task_ids` | array | — | 按任务 ID 列表过滤 |
| `filter.model` | string | — | 模型名，如 `MiniMax-H3` |
| `filter.task_type` | string | — | `generation` / `h3_context_ir` / `regeneration` |

响应为 `{"items": [ ...VideoTask ], "total": n}`，元素结构与查询单个任务的 `task` 一致。

```bash
curl "https://api.looprouter.com/v2/query/video_generation?page_num=1&page_size=20" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

## 取消 / 删除任务

`DELETE /v2/video_generation/{task_id}`

按任务当前状态执行不同动作：

| 当前状态 | 动作 | 说明 |
| --- | --- | --- |
| `queued` | `cancelled` | 处理前取消，不计费 |
| `succeeded` | `deleted` | 删除任务记录 |
| `failed` | `deleted` | 删除任务记录 |
| `running` | — | 不可操作，返回错误 |
| `cancelled` | — | 不可操作，返回错误 |

响应：

```json
{
  "task_id": "424010985738629",
  "action": "cancelled",
  "status": "cancelled"
}
```

该端点同样适用于 Context-IR 与视频再生的任务记录。

## 提示增强 · Context-IR

`POST /v2/h3_context_ir`

理解多模态上下文，输出一段**结构化增强提示词**，用于提升后续视频生成质量。它**不生成视频**：成功后 `task.content.prompt` 返回增强提示词，`modality` 为 `text`，按 token 计费。

请求参数与视频生成基本一致（`model`、`content`、`duration` 必填，`ratio`、`callback_url` 可选），差别是**没有** `resolution`。

```bash
curl -X POST "https://api.looprouter.com/v2/h3_context_ir" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "一个男孩在海边打篮球" }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'

# 返回：{"task_id": "426586401755526"} —— 轮询查询接口获取增强提示词
```

查询成功示例（`task_type` 为 `h3_context_ir`，`content.prompt` 承载增强提示词）：

```json
{
  "task": {
    "id": "426586401755526",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "content": {
      "prompt": "integrated_multimodal_description: [Shot 1] ... overall_soundscape: ... non_diegetic_music: ..."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "h3_context_ir",
    "modality": "text"
  }
}
```

## 视频再生 · Regeneration

`POST /v2/video_regeneration`

将符合 MiniMax-H3 **768P** 输出规格的源视频重生成为 **2K** 高清。输出恒为 `2K`，无需 `duration`。可用两种方式指定源视频，**二选一**（不能同时提供，也不能都不提供）：

<Tabs>
  <Tab title="方式一：按任务 ID">
    直接引用一个已成功的 `/v2/video_generation` 任务：

    | 字段 | 类型 | 必填 | 说明 |
    | --- | --- | --- | --- |
    | `model` | string | 是 | `MiniMax-H3` |
    | `source_task_id` | string | 是 | 源任务 ID，需属于当前账号、状态 `succeeded`、仍在 7 天查询窗口内 |
    | `resolution` | string | 是 | `2K` |
    | `aigc_watermark` | bool | 否 | 默认 `false` |
    | `callback_url` | string | 否 | 回调地址 |

    ```json
    {
      "model": "MiniMax-H3",
      "source_task_id": "424010985738629",
      "resolution": "2K"
    }
    ```
  </Tab>
  <Tab title="方式二：按源视频">
    `content` 必须包含生成 768P 源视频时的**全部原始输入**，外加**恰好一个** `type=video_url`、`role=base_video` 的源视频项。其中 `text` 必须是生成 768P 源视频时实际送入模型的最终 prompt（单条最长 40000 字符）。

    | 字段 | 类型 | 必填 | 说明 |
    | --- | --- | --- | --- |
    | `model` | string | 是 | `MiniMax-H3` |
    | `content` | array | 是 | 原始输入 + 1 个 `base_video` 源视频项 |
    | `resolution` | string | 是 | `2K` |
    | `aigc_watermark` | bool | 否 | 默认 `false` |
    | `callback_url` | string | 否 | 回调地址 |

    ```json
    {
      "model": "MiniMax-H3",
      "content": [
        { "type": "text", "text": "生成 768P 源视频时使用的最终 prompt" },
        {
          "type": "video_url",
          "video_url": { "url": "https://your-cdn.example.com/h3-768p.mp4" },
          "role": "base_video"
        }
      ],
      "resolution": "2K"
    }
    ```

    **`base_video` 源视频规格**：必须带音轨；帧率 24fps；宽高各能被 32 整除；面积（宽 × 高）≤ 768 × 1344（1,032,192 像素）；总帧数 107–362 帧（约 4–15 秒）。
  </Tab>
</Tabs>

两种方式都返回 `{"task_id": "..."}`，轮询查询接口获取结果；成功任务的 `task_type` 为 `regeneration`。

## 错误响应

所有错误采用 MiniMax 原生结构（顶层含 `type: "error"`）：

```json
{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit, please retry later (1002)",
    "http_code": "429"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}
```

| HTTP 状态码 | error.type | 常见原因 |
| --- | --- | --- |
| 400 | `bad_request_error` | 参数错误，如缺少非空 `text`、`resolution`/`duration` 取值非法 |
| 401 | `authorized_error` | API Key 缺失或无效 |
| 402 | `insufficient_balance_error` | 余额不足 |
| 422 | `unprocessable_entity_error` | 内容审核未通过（如涉敏内容） |
| 429 | `rate_limit_error` | 触发限流，请稍后重试 |
| 500 | `server_error` | 服务端异常，建议指数退避后重试 |

<Info>
错误 `message` 末尾括号内为上游内部错误码（如 `(1002)`）。429 与 5xx 建议指数退避重试（2s → 4s → 8s）。
</Info>

## 在线调试（试一试）

在 API 参考中可对每个 `/v2` 端点直接发起真实请求：

<CardGroup cols={3}>
  <Card title="创建视频任务" icon="flask" href="/api-reference/minimax/create-video-task">
    POST /v2/video_generation
  </Card>
  <Card title="查询任务" icon="flask" href="/api-reference/minimax/get-video-task">
    GET /v2/query/video_generation/{task_id}
  </Card>
  <Card title="任务列表" icon="flask" href="/api-reference/minimax/list-video-tasks">
    GET /v2/query/video_generation
  </Card>
  <Card title="取消 / 删除" icon="flask" href="/api-reference/minimax/delete-video-task">
    DELETE /v2/video_generation/{task_id}
  </Card>
  <Card title="提示增强 Context-IR" icon="flask" href="/api-reference/minimax/h3-context-ir">
    POST /v2/h3_context_ir
  </Card>
  <Card title="视频再生 768P→2K" icon="flask" href="/api-reference/minimax/video-regeneration">
    POST /v2/video_regeneration
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/minimax/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/minimax/h3-special.md

# MiniMax-H3 特惠版

> 通过独立 /special/v2 接口使用 MiniMax-H3 特惠版，支持 768P 与 2K 输出

特惠版使用独立的**特惠渠道**，请求尽量沿用 MiniMax-H3 的 `model`、`content`、`duration`、`resolution` 和 `ratio` 字段。客户端使用 LoopRouter 令牌，不需要任何额外凭据。

<Warning>
特惠版的路径以 `/special/v2` 开头，官方 MiniMax 渠道仍使用 `/v2`。两套渠道和任务互相隔离，查询任务时必须使用创建任务的那套接口。
</Warning>

## 创建视频

```bash
curl --request POST 'https://api.looprouter.com/special/v2/video_generation' \
  --header 'Authorization: Bearer YOUR_LOOPROUTER_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax-H3",
    "content": [{"type": "text", "text": "日出时分，海边的小船缓缓驶向远方"}],
    "duration": 5,
    "resolution": "768P",
    "ratio": "16:9"
  }'
```

返回异步任务 ID：

```json
{"task_id": "task_example"}
```

客户不需要处理任何内部路由参数。网关根据 `content` 中的素材角色选择文生、首帧/尾帧或多参考生成流程，并自动完成参数转换。

## 查询任务

```bash
curl 'https://api.looprouter.com/special/v2/query/video_generation/task_example' \
  --header 'Authorization: Bearer YOUR_LOOPROUTER_API_KEY'
```

响应沿用 MiniMax 的 `{ "task": { ... } }` 结构。视频处理期间为 `queued` 或 `running`，完成后为 `succeeded`，成片在 `task.content.url`。`h3_context_ir` 是文本任务，结果在 `task.content.prompt`。

## 接口列表

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/special/v2/video_generation` | 创建视频任务 |
| POST | `/special/v2/h3_context_ir` | 创建提示词增强任务 |
| POST | `/special/v2/video_regeneration` | 基于已有素材与提示词重新生成 2K 视频 |
| GET | `/special/v2/query/video_generation/{task_id}` | 查询任务 |
| GET | `/special/v2/query/video_generation` | 分页查询本账号特惠版任务 |
| DELETE | `/special/v2/video_generation/{task_id}` | 删除已结束的本地任务记录 |

特惠版不支持取消执行中的任务，此时请求删除会返回 501。已结束的任务可以删除本地记录，但不会删除已生成的媒体或退还已经结算的费用。不要将本地删除当作成功取消付费任务。

Context-IR 沿用创建视频的 `model`、`content`、`duration` 和 `ratio` 结构，但不带 `resolution`。单独调用再生成时，`content` 需包含实际生成源视频时使用的完整提示词、原始素材，以及一个 `type: "video_url"`、`role: "base_video"` 的源视频项。

Context-IR 的纯文本模式必须指定具体比例；多参考模式支持 `adaptive`（默认）；首尾帧模式由图片决定比例，`ratio` 不传给上游。

已有本账号通过特惠接口生成的成功 768P 任务时，也可用 `source_task_id` 代替整个 `content`。网关会读取原任务的提示词与素材；不能引用其他用户、官方渠道或文本任务。

```json
{"model":"MiniMax-H3","source_task_id":"task_example","resolution":"2K"}
```

## 分辨率与时长

| 参数 | 特惠版规则 |
| --- | --- |
| `resolution: "768P"` | 支持 |
| `resolution: "2K"` | 支持，任务完成后交付 2K 成片 |
| 其他分辨率 | 不自动替换为 768P，返回不支持错误 |
| 生成时长 | 5–15 秒整数；官方的 4 秒生成请求在特惠版中不支持 |
| Context-IR 时长 | 4–15 秒，与生成接口的范围不同 |

<Note>
请求 2K 时只需轮询原任务，任务完成后即获得 2K 成片，不需要创建第二个任务。
</Note>

## 与官方接口的区别

这里是协议适配，不是将请求原样转发到 MiniMax 官方。特惠版的时长、素材格式、宽高比及可选参数不一定覆盖官方所有能力；不能正确实现的参数会返回明确错误，不应依赖静默丢弃或替换。

- 生成请求必须显式传具体 `ratio`，不支持 `adaptive`，不会根据图片猜测比例。
- 素材使用公网 HTTP(S) URL，不支持官方的 `mm_file://` 或 Base64 data URI。
- 不支持 `callback_url`、`aigc_watermark` 或 `seed`；查询使用上面的轮询接口。
- 再生成源视频需要符合音轨、24fps、尺寸及帧数要求。仅标记为“768P”不能保证任意视频均兼容。
- 特惠版按分辨率与时长计费，不产生官方 token 用量账单，费用口径与官方渠道相互独立。

---

URL: https://docs.looprouter.com/api-capabilities/kling/overview.md

# 可灵 3.0 能力总览

> 可灵 3.0（Kling 3.0）系列视频模型：路径式 3.0 接口、六个模型、文/图/Omni 生成、动作控制、数字人、声音复刻与计费说明

可灵 3.0（Kling 3.0）是快手可灵的新一代视频生成模型，提供**标准版 `kling-3.0`**、**极速版 `kling-3.0-turbo`** 与**多模态版 `kling-3.0-omni`** 三档视频能力，覆盖文生视频、图生视频（首帧 / 尾帧 / 首尾帧）与 Omni 多模态融合生成（参考图 / 参考视频 / 主体元素）；并在此之上扩展了**动作控制 `kling-3.0-motion-control`**、**数字人 `kling-3.0-avatar`** 与**声音复刻 `kling-3.0-voice`** 三个专用能力，共 **6 个模型**。LoopRouter 以**对标可灵官方 3.0 的路径式接口**对外提供：视频生成走 `/text-to-video/{model}`、`/image-to-video/{model}`、`/omni-video/{model}`，动作控制走 `/motion-control/{model}`，数字人走 `/videos/avatar/image2video`，声音复刻走 `/general/custom-voices`；视频任务查询走 `GET /tasks`，数字人与声音复刻各有专属查询端点；Base URL 换成 `https://api.looprouter.com`、鉴权换成 LoopRouter 令牌即可。

<Note>
可灵 3.0 是**路径式**接口（模型名在 URL 路径里，如 `/text-to-video/kling-3.0`），请求体用 `settings` / `options` / `contents`。所有端点的路径都可**选**加 `/v1` 前缀（如 `/v1/text-to-video/kling-3.0`），行为完全一致，方便 Base URL 带 `/v1` 的可灵 SDK 直接接入；不加前缀是默认形态。它与旧版 body 式的 `/kling/v1` 接口是两套独立的 API，请勿混用。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    文生视频、图生视频、Omni 多模态与任务查询
  </Card>
  <Card title="在线调试（试一试）" icon="flask" href="/api-reference/kling/text-to-video">
    在文档内直接对可灵 3.0 端点发起真实请求
  </Card>
  <Card title="获取 API Key" icon="key" href="https://console.looprouter.com/keys">
    在控制台创建 `sk-` 令牌
  </Card>
</CardGroup>

## 核心特性

<CardGroup cols={2}>
  <Card title="六个模型" icon="layer-group">
    视频三档 `kling-3.0` / `kling-3.0-turbo` / `kling-3.0-omni`，外加动作控制、数字人、声音复刻
  </Card>
  <Card title="Omni 多模态融合" icon="wand-magic-sparkles">
    `/omni-video` 统一处理参考图、参考视频、基准视频与主体元素
  </Card>
  <Card title="动作控制 / 数字人 / 声音复刻" icon="person-running">
    参考视频驱动动作、音频驱动人像口型、音源克隆音色（`voice_id` 可回填数字人）
  </Card>
  <Card title="路径式原生接口" icon="plug">
    对标可灵官方 3.0 路径式 API，已有示例替换 Base URL 与令牌即可运行
  </Card>
</CardGroup>

## 模型清单

| 模型 | 说明 | 适用端点 |
| --- | --- | --- |
| `kling-3.0` | 可灵 3.0 标准版：文 / 图生视频，支持 `4k`、多镜头、原生音频 | `/text-to-video`、`/image-to-video` |
| `kling-3.0-turbo` | 可灵 3.0 Turbo 极速版：更快出片，分辨率通常至 `1080p` | `/text-to-video`、`/image-to-video` |
| `kling-3.0-omni` | 可灵 3.0 Omni 多模态版：融合参考图 / 参考视频 / 基准视频 / 主体元素统一生成 | `/omni-video` |
| `kling-3.0-motion-control` | 动作控制：用参考视频驱动图片 / 主体做出对应动作 | `/motion-control/{model}` |
| `kling-3.0-avatar` | 数字人：用音频驱动人像口型说话 | `/videos/avatar/image2video` |
| `kling-3.0-voice` | 声音复刻：克隆一段音源的音色，产出可复用的 `voice_id` | `/general/custom-voices` |

<Note>
前三个视频模型的模型名写在 URL 路径中（`/text-to-video/kling-3.0`），任务类型由**调用的端点**决定：`kling-3.0` 与 `kling-3.0-turbo` 走文生 / 图生端点，多模态融合用 `kling-3.0-omni` 走 `/omni-video`。动作控制、数字人、声音复刻是**专用端点**，计费模型由端点自动绑定：动作控制支持官方 `contents` / `settings` 或扁平结构两种请求形态（并存时以 `contents` / `settings` 优先），数字人与声音复刻请求体为扁平结构。
</Note>

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 生成模式 | 文生视频 / 图生视频（首帧、尾帧、首尾帧）/ Omni 多模态（参考图、参考视频、基准视频、主体元素） |
| 分辨率 | `720p` / `1080p` / `4k`（Turbo 通常至 `1080p`；具体可用档位以控制台「模型广场」为准） |
| 时长 | `duration` 为整数秒（常用 `5` / `10`），可用区间以模型档位为准 |
| 宽高比 | `16:9`（默认）/ `9:16` / `1:1` |
| 音频 | `native`（生成配套音频）/ `original`（保留参考视频原声，仅 Omni）/ `off`（默认静音） |
| 多镜头 | `multi_shot` 布尔，默认开启；用于多镜头分镜叙事 |
| 参考图 / 主体（Omni） | `refer_image` 传参考图后由网关自动创建主体，或用 `element` + `element_id` 引用既有主体 |
| 参考 / 基准视频（Omni） | `feature_video`（运镜 / 风格参考）、`base_video`（在其基础上续写 / 编辑） |
| 任务模式 | 异步任务：`submitted → processing → succeeded / failed` |
| 任务保留 | 成片 `url` 为限时链接，请及时转存 |

<Warning>
Omni 素材（`first_frame` / `last_frame` / `refer_image` / `feature_video` / `base_video` / `element`）与文本一起放在 `contents` 数组里；网关会按顺序把每个素材绑定进提示词，无需手动书写占位符。数量与组合限制以模型档位为准。
</Warning>

## 端点一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/text-to-video/{model}` | 文生视频（`kling-3.0` / `kling-3.0-turbo`） |
| POST | `/image-to-video/{model}` | 图生视频：首帧 / 尾帧 / 首尾帧（`kling-3.0` / `kling-3.0-turbo`） |
| POST | `/omni-video/{model}` | Omni 多模态生成（`kling-3.0-omni`） |
| POST | `/motion-control/{model}` | 动作控制（`kling-3.0-motion-control`；扁平别名 `/videos/motion-control`） |
| POST | `/videos/avatar/image2video` | 数字人提交（`kling-3.0-avatar`） |
| GET | `/videos/avatar/image2video/{task_id}` | 数字人查询（成功态 `succeed`） |
| POST | `/general/custom-voices` | 声音复刻提交（`kling-3.0-voice`） |
| GET | `/general/custom-voices/{task_id}` | 声音复刻查询（成功态 `succeed`） |
| GET | `/general/custom-voices` | 声音复刻列表（已复刻音色） |
| POST | `/general/advanced-custom-elements` | 创建自定义主体（主体管理，渠道级能力、不计费） |
| GET | `/general/advanced-custom-elements/{task_id}` | 查询自定义主体（返回 `element_id`） |
| GET | `/general/advanced-presets-elements` | 查询官方预置主体（分页） |
| GET | `/tasks` | 批量查询视频任务（`task_ids` 或 `external_task_ids`；含动作控制，不含数字人 / 声音复刻） |

<Tip>
所有接口统一使用 `Authorization: Bearer sk-...` 请求头，API Key 在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。以上路径均可**选**加 `/v1` 前缀（如 `/v1/text-to-video/{model}`），行为一致。
</Tip>

<Info>
视频类端点（文生 / 图生 / Omni / **动作控制**）统一走批量 `GET /tasks` 查询（`task_ids` 与 `external_task_ids` 支持逗号批量）。**数字人**与**声音复刻**各有专属查询端点——数字人走 `GET /videos/avatar/image2video/{task_id}`、声音复刻走 `GET /general/custom-voices/{task_id}`，二者成功态为 `succeed`（区别于视频端点的 `succeeded`），**不**走 `GET /tasks`。Omni 的参考主体通过 `contents` 里的 `refer_image` 自动创建。**文本转语音（TTS，`POST /audio/tts`）在本渠道不支持**，调用返回 `501`，请改用「声音复刻 + 数字人」组合（详见下方常见问题）。**主体管理**（创建 / 查询 / 官方预置列表）已开放，用参考图 / 参考视频定义可复用主体并产出 `element_id` 供 Omni / 动作控制引用（渠道级能力、不计费，详见[自定义主体](/api-capabilities/kling/custom-elements)）。暂未开放：主体的更新 / 删除、独立的音色管理 CRUD、单任务 `GET /tasks/{id}` 与游标分页 `POST /tasks`、回调（`callback_url`）投递。
</Info>

## 模型定价

不同能力有两种计费口径：**5 个视频模型按分辨率 × 时长（秒）计费**，**声音复刻按次计费**。

| 模型 | 计费方式 | 说明 |
| --- | --- | --- |
| `kling-3.0` / `kling-3.0-turbo` / `kling-3.0-omni` | 分辨率 × 时长 | 提交按参数预扣，完成按实际时长多退少补 |
| `kling-3.0-motion-control` | 分辨率 × 时长（**提交预扣 30 秒封顶**） | 输出时长由参考视频决定，提交时按 30 秒上限预扣、完成后回收 |
| `kling-3.0-avatar` | 分辨率 × 时长（**提交预扣 300 秒封顶**） | 输出时长跟随驱动音频（2-300 秒），提交时按 300 秒上限预扣、完成后回收 |
| `kling-3.0-voice` | **按次**（flat） | 每次提交按固定单价计费，非视频、无预扣回收 |

<Steps>
  <Step title="提交预扣">
    视频任务创建成功后按参数（分辨率、时长）预扣额度；动作控制 / 数字人在输出时长未知时按最大计费时长（30 秒 / 300 秒）预扣，因此提交时需保证余额充足。声音复刻在提交时一次性按次扣费。
  </Step>
  <Step title="完成结算">
    视频任务成功后按实际时长结算，多退少补；任务失败全额退回。声音复刻无二次结算。
  </Step>
</Steps>

<Info>
各分辨率每秒单价、动作控制 / 数字人的 `mode`（`std`→`720p`、`pro`→`1080p`）对应档位，以及声音复刻的按次单价，均以控制台「模型广场」与「日志中心」展示为准。实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率。
</Info>

## 限流与重试

- 收到 429 或 5xx 时，建议指数退避重试（2s → 4s → 8s）。
- 轮询查询接口建议间隔约 10 秒；`4k` 与长时长任务生成耗时更久，请适当延长轮询周期。

## 常见问题

<AccordionGroup>
  <Accordion title="它和旧版 /kling/v1 接口一样吗？">
    不一样。可灵 3.0 是**路径式**接口（`/text-to-video/{model}` 等，路径可**选**加 `/v1` 前缀，带与不带一致），请求体用 `settings` / `options` / `contents`，提交与查询响应用 `data.outputs[]`、状态枚举 `submitted / processing / succeeded / failed`。旧版 `/kling/v1` 是 body 式接口，二者独立。
  </Accordion>
  <Accordion title="创建任务后怎么拿到视频？">
    这是异步任务：提交返回任务 `id`，需轮询 `GET /tasks?task_ids={id}` 直到 `status` 为 `succeeded`，再从 `outputs[].url` 下载成片。
  </Accordion>
  <Accordion title="支持哪些分辨率？">
    `720p` / `1080p` / `4k`（Turbo 通常至 `1080p`）。在请求 `settings.resolution` 中设置，具体可用档位以控制台「模型广场」为准。
  </Accordion>
  <Accordion title="三个模型怎么选？">
    纯文 / 图生视频且追求速度 → `kling-3.0-turbo`；需要 `4k`、多镜头、原生音频 → `kling-3.0`；需要参考图 + 参考视频 + 主体融合的多模态生成 → `kling-3.0-omni`（走 `/omni-video`）。
  </Accordion>
  <Accordion title="支持数字人 / 动作控制 / 音色定制吗？">
    支持，三者都是**专用端点**：动作控制走 `POST /motion-control/{model}`（`kling-3.0-motion-control`，参考视频驱动图片 / 主体做动作，支持官方 `contents` / `settings` 或扁平结构 `/videos/motion-control` 两种形态），数字人走 `POST /videos/avatar/image2video`（`kling-3.0-avatar`，音频驱动人像口型），声音复刻走 `POST /general/custom-voices`（`kling-3.0-voice`，克隆音源音色）。查询上，动作控制属视频任务走 `GET /tasks`；数字人走专属 `GET /videos/avatar/image2video/{task_id}`、声音复刻走 `GET /general/custom-voices/{task_id}`，两者成功态为 `succeed`。声音复刻产出的 `voice_id` 可作为数字人的 `audio_id` 复用。此外[自定义主体](/api-capabilities/kling/custom-elements)（主体管理）已开放——用参考图 / 参考视频创建可复用主体、查询拿到 `element_id`，再在 Omni / 动作控制里以 `element` 引用（渠道级能力、不计费）。仍暂未开放的是：主体的更新 / 删除、音色管理 CRUD 与回调（`callback_url`）。
  </Accordion>
  <Accordion title="为什么没有单任务查询接口？">
    统一使用批量 `GET /tasks`，`task_ids` 与 `external_task_ids` 均支持逗号批量查询（一次只认一种，`task_ids` 优先）。游标分页 `POST /tasks` 暂未开放。
  </Accordion>
  <Accordion title="支持文本转语音（TTS）吗？">
    不支持。可灵官方的文本转语音端点 `POST /audio/tts`（含 `/v1` 别名）在本渠道**不可用**，调用会返回 `501 Not Implemented`。如需「用指定音色说话」，请走两步替代方案：先用[声音复刻](/api-capabilities/kling/voice-cloning) `POST /general/custom-voices` 克隆音色拿到 `voice_id`，再用[数字人](/api-capabilities/kling/video-generation#数字人) `POST /videos/avatar/image2video` 以该 `voice_id`（作 `audio_id`）驱动人像开口说话。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    参数、示例、三类生成端点与任务查询
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/kling/video-generation.md

# 可灵 3.0 视频生成 API

> 可灵 3.0 路径式任务接口：文生视频、图生视频、Omni 多模态、动作控制、数字人生成与批量任务查询

可灵 3.0 采用**异步任务**模式，接口对标可灵官方 3.0 路径式 API：先提交任务拿到 `id`，再轮询 `GET /tasks` 获取成片。模型名写在 URL 路径里（`/text-to-video/kling-3.0`），请求体用 `settings` / `options` / `contents` 三个字段组织参数。

<Warning>
**接入前请注意以下要点：**

1. Base URL 为 `https://api.looprouter.com`，端点是 `/text-to-video/{model}` 等；路径可**选**加 `/v1` 前缀（如 `/v1/text-to-video/{model}`），带与不带行为完全一致，方便可灵 SDK 直接接入。
2. 鉴权用 LoopRouter 令牌：`Authorization: Bearer sk-...`。
3. `model` 写在路径中：`kling-3.0` / `kling-3.0-turbo` 走文生 / 图生端点，`kling-3.0-omni` 走 `/omni-video`。
4. `settings.resolution` 取 `720p` / `1080p` / `4k`；`settings.duration` 为整数秒。
5. 成功状态是 `succeeded`；成片 `outputs[].url` 为限时链接，请尽快转存。
6. 回调（`options.callback_url`）当前**不投递**，请通过轮询 `GET /tasks` 获取结果。
</Warning>

## 创建视频任务

三个提交端点共用同一套请求体结构（`prompt` + `settings` + `options` + `contents`），仅 `contents` 的组合不同。

<CodeGroup>

```bash 文生视频（cURL）
curl -X POST "https://api.looprouter.com/text-to-video/kling-3.0" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "prompt": "一只柯基犬在草地上奔跑，阳光明媚，慢镜头",
    "settings": {
      "resolution": "1080p",
      "aspect_ratio": "16:9",
      "duration": 5,
      "audio": "native",
      "multi_shot": true
    }
  }'

# 返回：{"code":0,"message":"SUCCEED","request_id":"...","data":{"id":"task_xxxx","status":"submitted","create_time":1781080778802,"update_time":1781080778802}}
```

```python 完整流程（Python）
import time
import requests

BASE = "https://api.looprouter.com"
HEADERS = {"Authorization": "Bearer sk-你的APIKey"}

# 1. 创建任务
resp = requests.post(
    f"{BASE}/text-to-video/kling-3.0",
    headers=HEADERS,
    json={
        "prompt": "一只柯基犬在草地上奔跑，阳光明媚，慢镜头",
        "settings": {
            "resolution": "1080p",
            "aspect_ratio": "16:9",
            "duration": 5,
            "audio": "native",
        },
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["id"]
print("任务已创建:", task_id)

# 2. 轮询任务状态（建议 10 秒一次）
while True:
    data = requests.get(
        f"{BASE}/tasks",
        headers=HEADERS,
        params={"task_ids": task_id},
    ).json()["data"]
    task = data[0]
    status = task["status"]
    print("当前状态:", status)
    if status in ("succeeded", "failed"):
        break
    time.sleep(10)

# 3. 下载成片（下载时不要携带 Authorization 头）
if status == "succeeded":
    video_url = task["outputs"][0]["url"]
    with requests.get(video_url, stream=True) as r:
        r.raise_for_status()
        with open("output.mp4", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)
    print("已保存 output.mp4")
else:
    print("任务失败:", task_id)
```

```json 图生视频（首帧 / 首尾帧）
// POST /image-to-video/kling-3.0
// 首帧：contents 放 1 张 first_frame；首尾帧：再加 1 张 last_frame
{
  "prompt": "镜头缓缓推进，人物转身微笑，从清晨过渡到黄昏",
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "audio": "native"
  },
  "contents": [
    { "type": "first_frame", "url": "https://example.com/first.jpg" },
    { "type": "last_frame", "url": "https://example.com/last.jpg" }
  ]
}
```

```json Omni 多模态（参考图 + 参考视频）
// POST /omni-video/kling-3.0-omni
// contents 里放 refer_image / feature_video / base_video / element 等素材，
// 网关按顺序自动把素材绑定进提示词，无需手写占位符。
{
  "prompt": "让参考图中的角色在城市夜景中行走，参考该视频的运镜与节奏",
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "audio": "original"
  },
  "options": {
    "external_task_id": "my-biz-001"
  },
  "contents": [
    { "type": "refer_image", "url": "https://example.com/character.jpg" },
    { "type": "feature_video", "url": "https://example.com/motion.mp4" }
  ]
}
```

</CodeGroup>

### 请求参数速查

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `prompt` | string | 条件 | 主提示词。文生视频必填；也可作为 `contents` 里的 `type=prompt` 项提供 |
| `settings` | object | 否 | 生成设置，见 [settings 字段](#settings-字段) |
| `options` | object | 否 | 任务选项，见 [options 字段](#options-字段) |
| `contents` | array | 条件 | 素材数组：图生视频与 Omni 必填，见 [contents 数组](#contents-数组) |

### settings 字段

| 字段 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `resolution` | string | `720p` | `720p` / `1080p` / `4k`（Turbo 通常至 `1080p`） |
| `aspect_ratio` | string | `16:9` | `16:9` / `9:16` / `1:1` |
| `duration` | int | 模型默认 | 输出时长（整数秒），如 `5` / `10` |
| `audio` | string | `off` | `native` 生成配套音频；`original` 保留参考视频原声（仅 Omni 的 `feature_video`）；`off` 静音 |
| `multi_shot` | bool | `true` | 多镜头分镜叙事开关 |

<Info>
仅传入的字段会覆盖网关默认值，省略的字段沿用模型档位默认。`multi_shot` 用指针区分「未设置」与「显式 `false`」，需要关闭多镜头时请显式传 `false`。
</Info>

### options 字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `external_task_id` | string | 否 | 业务自定义 ID，回显在任务 `external_id`，可用 `GET /tasks?external_task_ids=` 反查 |
| `watermark_info.enabled` | bool | 否 | 是否叠加水印 |
| `callback_url` | string | 否 | 预留字段，**当前不投递回调**，请改用轮询 `GET /tasks` |

### contents 数组

每个元素由 `type` 决定读取哪些字段。图生视频用 `first_frame` / `last_frame`；Omni 可组合多种素材：

| type | 字段 | 适用端点 | 说明 |
| --- | --- | --- | --- |
| `prompt` | `text` | 全部 | 提示词，等价于顶层 `prompt` |
| `first_frame` | `url` | 图生 / Omni | 首帧图 |
| `last_frame` | `url` | 图生 / Omni | 尾帧图 |
| `refer_image` | `url` | Omni | 参考图；网关自动为其创建主体元素 |
| `feature_video` | `url` | Omni | 参考视频（运镜 / 风格；`audio=original` 时保留其原声） |
| `base_video` | `url` | Omni | 基准视频，在其基础上续写 / 编辑 |
| `element` | `element_id` | Omni | 引用既有主体，传数字 `element_id` |

<Note>
Omni 生成时，网关会按 `contents` 中素材出现的顺序把它们绑定进提示词，你只需在 `prompt` 中自然描述即可，无需手动书写素材占位符。
</Note>

<Tip>
`element` 引用的 `element_id` 来自[自定义主体](/api-capabilities/kling/custom-elements)（主体管理）：用参考图 / 参考视频**显式创建一个可复用主体**，查询成功后拿到数字 `element_id`，即可让同一主体在多次生成中保持一致。这与 `refer_image` 传图后由网关**临时**创建主体不同——后者一次性，前者可复用。
</Tip>

### 三类生成端点

| 端点 | 模型 | contents 组合 |
| --- | --- | --- |
| `POST /text-to-video/{model}` | `kling-3.0` / `kling-3.0-turbo` | 仅 `prompt` + `settings`（可省略 `contents`） |
| `POST /image-to-video/{model}` | `kling-3.0` / `kling-3.0-turbo` | `prompt` + `first_frame`（可加 `last_frame`） |
| `POST /omni-video/{model}` | `kling-3.0-omni` | `prompt` + 若干 Omni 素材（`refer_image` / `feature_video` / `base_video` / `element`） |

提交成功返回统一的 ack 信封，`data.id` 为网关任务 ID（后续查询用它）：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "0217852290155100a2c883cf675b9804d",
  "data": {
    "id": "task_xxxx",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080778802,
    "external_id": "my-biz-001"
  }
}
```

## 动作控制

`POST /motion-control/{model}` · 模型 `kling-3.0-motion-control`

动作控制（Motion Control）用一段**参考视频**驱动图片中的角色 / 主体做出对应动作。它是**专用端点**，计费模型由端点自动绑定（路径里的 `{model}` 仅作占位，写 `kling-3.0` 或 `kling-3.0-motion-control` 均可）。请求体支持两种形态：**官方 `contents` + `settings`**（推荐，与可灵官方一致），或**扁平结构**（顶层直接放 `image_url` / `video_url` / `mode` 等，作兼容别名，走 `POST /videos/motion-control`）。两者并存时以 `contents` / `settings` 优先。

<CodeGroup>

```bash 官方形态（contents + settings）
curl -X POST "https://api.looprouter.com/motion-control/kling-3.0" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "contents": [
      { "type": "image", "url": "https://example.com/char.png" },
      { "type": "video", "url": "https://example.com/drive.mp4" },
      { "type": "prompt", "text": "the character dances energetically" }
    ],
    "settings": {
      "character_orientation": "video",
      "audio": "original",
      "resolution": "720p"
    }
  }'
```

```bash 扁平形态（兼容别名）
curl -X POST "https://api.looprouter.com/videos/motion-control" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "prompt": "the character dances energetically",
    "image_url": "https://example.com/char.png",
    "video_url": "https://example.com/drive.mp4",
    "mode": "std",
    "character_orientation": "video",
    "keep_original_sound": "yes",
    "watermark_info": { "enabled": false }
  }'
```

</CodeGroup>

**官方形态** —— `contents[]` 按内容顺序给出角色图片、参考视频与描述，`settings` 控制朝向、原声与分辨率：

| `contents[].type` | 字段 | 说明 |
| --- | --- | --- |
| `image`（或 `refer_image` / `first_frame`） | `url` | 被驱动的角色 / 主体图片 |
| `video`（或 `feature_video` / `base_video`） | `url` | 提供动作的参考视频 |
| `prompt` | `text` | 补充描述 |
| `element` | `element_id` | 引用既有主体 |

| `settings` 字段 | 取值 | 说明 |
| --- | --- | --- |
| `character_orientation` | `image` / `video` | 动作朝向对齐基准 |
| `audio` | `original` / `native` / `off` | `original` / `native` 保留参考视频原声，`off` 静音 |
| `resolution` | `720p` / `1080p` | 决定计费档位（`720p`→`std`、`1080p`→`pro`） |

**扁平形态**（兼容别名，`POST /videos/motion-control`）：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `image_url` | string | 是 | 被驱动的角色 / 主体图片 URL |
| `video_url` | string | 是 | 提供动作的参考视频 URL |
| `mode` | string | 是 | `std`（→ `720p` 档）/ `pro`（→ `1080p` 档），决定计费档位 |
| `character_orientation` | string | 是 | 动作朝向对齐基准：`image`（对齐图片）/ `video`（对齐参考视频） |
| `prompt` | string | 否 | 补充描述 |
| `keep_original_sound` | string | 否 | 是否保留参考视频原声：`"yes"` / `"no"`（字符串，非布尔） |
| `watermark_info.enabled` | bool | 否 | 是否叠加水印 |

<Info>
输出时长由参考视频决定、提交时未知，网关按**最大计费时长 30 秒**预扣，任务完成后按实际时长回收多退少补（见[计费规则](/api-capabilities/kling/overview#模型定价)），因此提交时请保证余额充足。上游以 `model_name: "kling-v3"` 提交。
</Info>

动作控制**是视频任务**，提交成功返回与文 / 图 / Omni 一致的 ack 信封（`data.id` 为网关任务 ID、`data.status`），后续**统一走 `GET /tasks` 查询**：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101345034646613008268d9d64xm9uHKV",
  "data": {
    "id": "task_xxxx",
    "status": "submitted",
    "create_time": 1786369503495,
    "update_time": 1786369503495
  }
}
```

## 数字人

`POST /videos/avatar/image2video` · 模型 `kling-3.0-avatar`

数字人（Avatar）用一段**音频**驱动人像图片开口说话（口型对齐）。同为**专用端点**、请求体**扁平结构**（不使用 `settings` / `contents`），计费模型由端点自动绑定。

```bash cURL
curl -X POST "https://api.looprouter.com/videos/avatar/image2video" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "image": "https://example.com/face.png",
    "audio_id": "voice-abc-123",
    "prompt": "news anchor reading headlines",
    "mode": "std",
    "watermark_info": { "enabled": false }
  }'
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `image` | string | 是 | 被驱动的人像图片 URL |
| `audio_id` | string | 条件 | 驱动音频 ID；可直接填[声音复刻](/api-capabilities/kling/voice-cloning)产出的 `voice_id`。与 `sound_file` 二选一 |
| `sound_file` | string | 条件 | 直接提供驱动音频文件 URL，与 `audio_id` 二选一 |
| `mode` | string | 否 | `std`（→ `720p` 档）/ `pro`（→ `1080p` 档），决定计费档位 |
| `prompt` | string | 否 | 补充描述 |
| `watermark_info.enabled` | bool | 否 | 是否叠加水印 |

<Info>
输出时长跟随驱动音频（约 2–300 秒）、提交时未知，网关按**最大计费时长 300 秒**预扣，完成后按实际时长回收多退少补。`pro`（1080p）单价更高，请预留足够余额。上游数字人请求体**不带 `model_name` 字段**。
</Info>

数字人的提交与查询**不走视频任务那套 ack / `GET /tasks`**，而是**专属信封**：提交返回 `data.task_id` / `data.task_status`，成功态是 **`succeed`**（注意——不是视频端点的 `succeeded`），并用**专属查询端点**拉取结果。提交响应：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101348177602932008268d9d6f5NscS8V",
  "data": {
    "task_id": "task_xxxx",
    "task_status": "submitted",
    "task_status_msg": "",
    "created_at": 1786369697787,
    "updated_at": 1786369697787
  }
}
```

用专属端点查询（**不要**用 `GET /tasks`）：

`GET /videos/avatar/image2video/{task_id}`

```bash cURL
curl "https://api.looprouter.com/videos/avatar/image2video/task_xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

成功时 `task_status` 为 `succeed`，成片在 `data.task_result.videos[]`（`id` / `url` / `duration`）：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101351020000000008268d9d70abc",
  "data": {
    "task_id": "task_xxxx",
    "task_status": "succeed",
    "task_status_msg": "",
    "task_result": {
      "videos": [
        {
          "id": "task_xxxx",
          "url": "https://api.looprouter.com/v1/videos/task_xxxx/content",
          "duration": "8"
        }
      ]
    },
    "created_at": 1786369697787,
    "updated_at": 1786369730000
  }
}
```

<Note>
声音复刻（`kling-3.0-voice`）是**非视频**的独立任务，请求体、计费与查询方式都不同（同样是 `task_id` / `succeed` 专属信封 + 专属查询端点），详见[声音复刻 API](/api-capabilities/kling/voice-cloning)。
</Note>

## 查询任务

`GET /tasks`

批量查询任务，`task_ids` 与 `external_task_ids` **二选一**（一次只认一种，`task_ids` 优先），均支持逗号分隔批量。文生 / 图生 / Omni / **动作控制**四类视频任务都用它查询，任务状态机：`submitted → processing → succeeded / failed`。**数字人**与**声音复刻**不在此列 —— 它们各有专属查询端点（`GET /videos/avatar/image2video/{task_id}`、`GET /general/custom-voices/{task_id}`），成功态是 `succeed`。

| 查询参数 | 说明 |
| --- | --- |
| `task_ids` | 网关任务 ID 列表，逗号分隔，如 `task_a,task_b` |
| `external_task_ids` | 业务自定义 ID 列表（`options.external_task_id`），逗号分隔 |

```bash 按任务 ID 查询
curl "https://api.looprouter.com/tasks?task_ids=task_xxxx,task_yyyy" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

```bash 按业务 ID 查询
curl "https://api.looprouter.com/tasks?external_task_ids=my-biz-001" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

响应 `data` **恒为数组**，每个元素结构如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 任务 ID |
| `status` | string | `submitted` / `processing` / `succeeded` / `failed` |
| `create_time` / `update_time` | int | Unix 毫秒时间戳 |
| `external_id` | string | 回显 `options.external_task_id`（若有） |
| `outputs` | array | 成片产物数组，成功时含 `id` / `url` / `duration` |

`outputs[]` 元素：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 产物 ID（与任务 `id` 一致） |
| `url` | string | 成片下载地址（限时链接） |
| `duration` | string | 成片时长（秒） |

成功响应示例：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "0217852290155100a2c883cf675b9804d",
  "data": [
    {
      "id": "task_xxxx",
      "status": "succeeded",
      "create_time": 1781080778802,
      "update_time": 1781080794151,
      "external_id": "my-biz-001",
      "outputs": [
        {
          "id": "task_xxxx",
          "url": "https://api.looprouter.com/v1/videos/task_xxxx/content",
          "duration": "5"
        }
      ]
    }
  ]
}
```

处理中 / 失败示例（`outputs` 为空数组）：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "0217852290155100a2c883cf675b9804d",
  "data": [
    { "id": "task_yyyy", "status": "processing", "create_time": 1781080778802, "update_time": 1781080780000, "outputs": [] },
    { "id": "task_zzzz", "status": "failed", "create_time": 1781080778802, "update_time": 1781080790000, "outputs": [] }
  ]
}
```

<Warning>
`outputs[].url` 为**限时下载链接**，请及时转存；下载时请求中**不要**携带 `Authorization` 头。
</Warning>

## 错误响应

参数错误、鉴权失败或上游异常时返回错误信封：

| HTTP 状态码 | 常见原因 |
| --- | --- |
| 400 | 参数错误，如缺少 `prompt`、`resolution` 取值非法、`task_ids` 与 `external_task_ids` 均缺失 |
| 401 | API Key 缺失或无效 |
| 429 | 触发限流，请稍后重试 |
| 500 | 服务端异常，建议指数退避后重试 |

<Info>
429 与 5xx 建议指数退避重试（2s → 4s → 8s）。任务本身的失败不体现为 HTTP 错误，而是查询时 `status` 为 `failed`。
</Info>

## 在线调试（试一试）

在 API 参考中可对每个端点直接发起真实请求：

<CardGroup cols={2}>
  <Card title="文生视频" icon="flask" href="/api-reference/kling/text-to-video">
    POST /text-to-video/{model}
  </Card>
  <Card title="图生视频" icon="flask" href="/api-reference/kling/image-to-video">
    POST /image-to-video/{model}
  </Card>
  <Card title="Omni 多模态生成" icon="flask" href="/api-reference/kling/omni-video">
    POST /omni-video/{model}
  </Card>
  <Card title="动作控制" icon="flask" href="/api-reference/kling/motion-control">
    POST /motion-control/{model}
  </Card>
  <Card title="数字人提交" icon="flask" href="/api-reference/kling/avatar">
    POST /videos/avatar/image2video
  </Card>
  <Card title="数字人查询" icon="flask" href="/api-reference/kling/get-avatar">
    GET /videos/avatar/image2video/{task_id}
  </Card>
  <Card title="任务查询" icon="flask" href="/api-reference/kling/list-tasks">
    GET /tasks
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/kling/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个任务
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/kling/custom-elements.md

# 可灵 3.0 自定义主体 API

> 可灵 3.0 高级自定义主体（advanced custom elements / 主体管理）：用参考图或参考视频定义可复用主体，产出 element_id 供 Omni / 动作控制引用，渠道级能力、不计费

高级自定义主体（advanced custom elements，又称**主体管理**）用一组**参考图**或一段**参考视频**定义一个**可复用主体**（一个角色 / 一个物体 / 一个 IP 形象）。创建并查询成功后拿到的 `element_id`，可直接在 [Omni 多模态生成](/api-capabilities/kling/video-generation#omni-多模态)与[动作控制](/api-capabilities/kling/video-generation#动作控制)中通过 `element` 素材引用，让同一主体在多次生成里保持一致。

与 Omni 里 `refer_image` 传图后**由网关临时创建主体**不同，这里创建的是**显式、可复用、可命名**的主体：一次创建，多次引用。

<Warning>
主体管理与视频任务在三处不同，接入时请注意：

1. **`task_id` 是网关签名的不透明令牌**：创建 / 预置列表返回的 `data.task_id` 恒以 `ace_` 开头，**不是**上游原始 ID。后续查询**必须原样使用**该令牌——它无状态地把查询路由回**创建时的同一渠道**（创建与查询是两次独立请求，令牌自带渠道信息才能命中同一上游账号）。请勿自行拼接或改写。
2. **渠道级能力、不计费**：主体的创建 / 查询 / 预置列表**不扣费**，也不是任务提交，不走计费管线。
3. **路径可选 `/v1` 前缀**：三个端点均可写成 `/v1/general/advanced-custom-elements...`，带与不带行为一致。
</Warning>

## 创建自定义主体

`POST /general/advanced-custom-elements`

用参考图（`image_refer`）或参考视频（`video_refer`）创建一个主体。

```bash cURL
curl -X POST "https://api.looprouter.com/general/advanced-custom-elements" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "element_name": "my-hero",
    "element_description": "一位身穿红色斗篷的动画英雄",
    "reference_type": "image_refer",
    "element_image_list": {
      "frontal_image": "https://example.com/hero-front.png",
      "refer_images": [
        { "image_url": "https://example.com/hero-side.png" },
        { "image_url": "https://example.com/hero-back.png" }
      ]
    },
    "tag_list": [{ "tag_id": "o_101" }]
  }'
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `element_name` | string | 是 | 主体名称，长度 ≤ 20 |
| `element_description` | string | 是 | 主体描述，长度 ≤ 100 |
| `reference_type` | string | 是 | `image_refer`（用参考图）/ `video_refer`（用参考视频） |
| `element_image_list` | object | 条件 | `reference_type=image_refer` 时必填，见下 |
| `element_video_list` | object | 条件 | `reference_type=video_refer` 时必填，见下 |
| `element_voice_id` | string | 否 | 绑定的音色 ID，**仅 `video_refer` 主体可绑定** |
| `tag_list` | array | 否 | 主体标签，元素为 `{ "tag_id": "o_101" }`，`tag_id` 枚举 `o_101`~`o_108` |

`element_image_list`（`image_refer`）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `frontal_image` | string | **1 张正脸图** URL |
| `refer_images` | array | **1~3 张**其他角度参考图，元素为 `{ "image_url": "..." }` |

<Info>
图片要求：`.jpg` / `.jpeg` / `.png` 或 Base64URL；单张 ≤ 10MB，短边 ≥ 300px，宽高比 1:2.5 ~ 2.5:1。
</Info>

`element_video_list`（`video_refer`）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `refer_videos` | array | **至多 1 段**参考视频，元素为 `{ "video_url": "..." }` |

<Info>
视频要求：MP4 / MOV，时长 3~8 秒，宽高比 16:9 或 9:16，≤ 200MB。
</Info>

提交成功返回创建 ack，`data.task_id` 为网关签名令牌（**创建 ack 无 `task_result`**，用该令牌查询才拿到 `element_id`）：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608131429431085002008268d9d6gxQi3MuZ",
  "data": {
    "task_id": "ace_NjA6dHNrLWFiYzEyMw.4f3c…",
    "task_status": "submitted",
    "created_at": 1786372183136,
    "updated_at": 1786372183136
  }
}
```

## 查询自定义主体

`GET /general/advanced-custom-elements/{task_id}`

用创建返回的 `task_id` 令牌查询主体。任务状态机：`submitted → processing → succeed / failed`。

```bash cURL
curl "https://api.looprouter.com/general/advanced-custom-elements/ace_NjA6dHNrLWFiYzEyMw.4f3c…" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

响应 `data` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | 网关签名令牌（回显你持有的那个 `ace_` 令牌） |
| `task_status` | string | `submitted` / `processing` / `succeed` / `failed` |
| `task_status_msg` | string | 失败原因（若有） |
| `task_result` | object | 成功时出现，含 `elements[]` |
| `created_at` / `updated_at` | int | Unix 毫秒时间戳 |

`task_result.elements[]` 元素（关键字段）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `element_id` | number | **主体 ID**，用于 Omni / 动作控制的 `element` 引用 |
| `element_name` | string | 主体名称 |
| `element_description` | string | 主体描述 |
| `element_type` | string | `image_refer` / `video_refer`（注意：响应里是 `element_type`，创建请求里是 `reference_type`） |
| `element_image_list` | object | 参考图集合（`image_refer` 主体） |
| `element_video_list` | object | 参考视频集合（`video_refer` 主体） |
| `element_voice_info` | object | 绑定音色信息（若有）：`voice_id` / `voice_name` / `trial_url` |
| `tag_list` | array | 标签，元素为 `{ id, name, description }` |

成功响应示例：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608131430078425945008268d9d6ZEra2TSv",
  "data": {
    "task_id": "ace_NjA6dHNrLWFiYzEyMw.4f3c…",
    "task_status": "succeed",
    "task_result": {
      "elements": [
        {
          "element_id": 171,
          "element_name": "my-hero",
          "element_description": "一位身穿红色斗篷的动画英雄",
          "element_type": "image_refer",
          "element_image_list": {
            "frontal_image": "https://example.com/hero-front.png",
            "refer_images": [
              { "image_url": "https://example.com/hero-side.png" },
              { "image_url": "https://example.com/hero-back.png" }
            ]
          },
          "tag_list": [
            { "id": "o_101", "name": "animal", "description": "The content of description." }
          ]
        }
      ]
    },
    "created_at": 1786372183000,
    "updated_at": 1786372184000
  }
}
```

## 查询官方预置主体

`GET /general/advanced-presets-elements`

分页查询可灵**官方预置**主体列表，可直接引用其 `element_id`，无需自己创建。

```bash cURL
curl "https://api.looprouter.com/general/advanced-presets-elements?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `pageNum` | int | 否 | 页码，默认 1（缺省或非正数交由上游取默认值） |
| `pageSize` | int | 否 | 每页条数，默认 30（缺省或非正数交由上游取默认值） |

`data` 恒为**数组**，每项结构同「查询自定义主体」的 `data`（含 `task_result.elements[]`），每条的 `task_id` 同样是网关签名令牌。

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608131431556730001008268d9d6ListVz",
  "data": [
    {
      "task_id": "ace_cHJlc2V0OjE2MA.9a1b…",
      "task_status": "succeed",
      "task_result": {
        "elements": [
          { "element_id": 160, "element_name": "preset-cat", "element_type": "image_refer" }
        ]
      },
      "created_at": 1786372183000,
      "updated_at": 1786372184000
    }
  ]
}
```

## 用 element_id 生成视频

拿到 `element_id` 后，在 [Omni](/api-capabilities/kling/video-generation#omni-多模态)（`POST /omni-video/{model}`）或[动作控制](/api-capabilities/kling/video-generation#动作控制)（`POST /motion-control/{model}`）的 `contents` 里用 `element` 素材引用它：

```json
{
  "contents": [
    { "type": "prompt", "text": "英雄在雨中奔跑" },
    { "type": "element", "element_id": 171 }
  ],
  "settings": { "resolution": "1080p", "duration": 5 }
}
```

<Note>
`element` 素材传**数字** `element_id`（查询响应里的数字，而非 `ace_` 令牌）。`ace_` 令牌只用于主体查询端点；生成端点引用主体用的是 `element_id`。
</Note>

## 计费

<Info>
主体管理（创建 / 查询 / 预置列表）是**渠道级能力，不计费**：这些调用不扣费、不产生消费日志。实际产生费用的是随后用 `element_id` 发起的[视频生成](/api-capabilities/kling/overview#模型定价)（Omni / 动作控制按分辨率 × 时长计费）。
</Info>

## 在线调试（试一试）

<CardGroup cols={2}>
  <Card title="创建自定义主体" icon="flask" href="/api-reference/kling/create-custom-element">
    POST /general/advanced-custom-elements
  </Card>
  <Card title="查询自定义主体" icon="flask" href="/api-reference/kling/get-custom-element">
    GET /general/advanced-custom-elements/{task_id}
  </Card>
  <Card title="查询官方预置主体" icon="flask" href="/api-reference/kling/list-preset-elements">
    GET /general/advanced-presets-elements
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    Omni / 动作控制里如何用 element 引用主体
  </Card>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/kling/overview">
    模型清单、技术规格、计费规则
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/kling/voice-cloning.md

# 可灵 3.0 声音复刻 API

> 可灵 3.0 声音复刻（voice cloning）：克隆一段音源的音色，产出可复用的 voice_id，按次计费

声音复刻用一段音源**克隆音色**，产出一个可复用的 `voice_id`，可直接作为[数字人](/api-capabilities/kling/video-generation#数字人)的 `audio_id` 使用。它是**非视频**的独立任务，计费模型恒为 `kling-3.0-voice`。

<Warning>
声音复刻与视频任务在三处不同，接入时请注意：

1. **专用端点、扁平请求体**：`POST /general/custom-voices`，顶层直接放字段，不使用 `settings` / `contents`。
2. **响应字段名不同**：提交与查询响应用 `data.task_id` / `data.task_status`（**不是**视频的 `id` / `status`）；成功状态是 **`succeed`**（注意**不是**视频的 `succeeded`）。
3. **独立查询端点**：单条结果走 `GET /general/custom-voices/{task_id}`，列表走 `GET /general/custom-voices`，都**不走** `GET /tasks`。
4. **路径可选 `/v1` 前缀**：三个端点均可写成 `/v1/general/custom-voices...`，带与不带行为一致。
</Warning>

## 提交复刻任务

`POST /general/custom-voices` · 模型 `kling-3.0-voice`

```bash cURL
curl -X POST "https://api.looprouter.com/general/custom-voices" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "voice_name": "my-anchor-voice",
    "voice_url": "https://example.com/sample-voice.mp3"
  }'
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `voice_name` | string | 是 | 音色名称，长度 ≤ 20 |
| `voice_url` | string | 否 | 音源文件 URL（`.mp3` / `.wav` / `.mp4` / `.mov`，建议 5–30 秒） |

提交成功返回 ack 信封，`data.task_id` 为网关任务 ID（后续查询用它）：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101429431085002008268d9d6gxQi3MuZ",
  "data": {
    "task_id": "task_xxxx",
    "task_status": "submitted",
    "created_at": 1786372183136,
    "updated_at": 1786372183136
  }
}
```

## 查询复刻任务

`GET /general/custom-voices/{task_id}`

用提交返回的 `task_id` 查询进度。任务状态机：`submitted → processing → succeed / failed`。

```bash cURL
curl "https://api.looprouter.com/general/custom-voices/task_xxxx" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

响应 `data` 字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | 任务 ID |
| `task_status` | string | `submitted` / `processing` / `succeed` / `failed` |
| `task_status_msg` | string | 失败原因（若有） |
| `task_result` | object | 成功时出现，含 `voices[]` |
| `created_at` / `updated_at` | int | Unix 毫秒时间戳 |

`task_result.voices[]` 元素：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `voice_id` | string | 复刻出的音色 ID，可作为数字人的 `audio_id` 复用 |
| `voice_name` | string | 音色名称 |
| `trial_url` | string | 试听音频链接（限时） |
| `owned_by` | string | 归属标识 |

成功响应示例：

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101430078425945008268d9d6ZEra2TSv",
  "data": {
    "task_id": "task_xxxx",
    "task_status": "succeed",
    "task_result": {
      "voices": [
        {
          "voice_id": "voice-voicetask-1",
          "voice_name": "demo-cloned",
          "trial_url": "https://api.looprouter.com/voice/voicetask-1.mp3",
          "owned_by": "looprouter"
        }
      ]
    },
    "created_at": 1786372183000,
    "updated_at": 1786372184000
  }
}
```

## 列出已复刻音色

`GET /general/custom-voices`

列出当前令牌下已复刻的音色。`data` 恒为**数组**，每项是一条复刻任务的 ack 信封（`task_id` / `task_status` / 成功时的 `task_result.voices[]`），成功态同为 `succeed`。无查询参数。

```bash cURL
curl "https://api.looprouter.com/general/custom-voices" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

```json
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "202608101431556730001008268d9d6ListVz",
  "data": [
    {
      "task_id": "task_xxxx",
      "task_status": "succeed",
      "task_result": {
        "voices": [
          {
            "voice_id": "voice-voicetask-1",
            "voice_name": "demo-cloned",
            "trial_url": "https://api.looprouter.com/voice/voicetask-1.mp3",
            "owned_by": "looprouter"
          }
        ]
      },
      "created_at": 1786372183000,
      "updated_at": 1786372184000
    }
  ]
}
```

## 计费

<Info>
声音复刻**按次计费**（flat）：每次提交按固定单价一次性扣费，无预扣回收、无二次结算，任务失败不额外扣费。单价以控制台「模型广场」与「日志中心」展示为准；实际扣费还会应用 API Key 所在[分组](/user-groups)的计费倍率。
</Info>

与视频任务的「提交预扣、完成结算」两段式计费不同，声音复刻在提交时一次性扣费。详见[能力总览 · 模型定价](/api-capabilities/kling/overview#模型定价)。

## 与数字人联动

复刻成功后拿到的 `voice_id`，可直接作为[数字人](/api-capabilities/kling/video-generation#数字人) `POST /videos/avatar/image2video` 的 `audio_id`，用复刻音色驱动人像说话：

```json
{
  "image": "https://example.com/face.png",
  "audio_id": "voice-voicetask-1",
  "mode": "std"
}
```

<Note>
本渠道不提供文本转语音（TTS，`POST /audio/tts` 返回 `501`）。要「用指定音色说一段话」，请走这里的「声音复刻 → 数字人」组合：先复刻拿到 `voice_id`，再用数字人以该音色驱动人像开口，而非直接合成语音。
</Note>

## 在线调试（试一试）

<CardGroup cols={2}>
  <Card title="提交复刻任务" icon="flask" href="/api-reference/kling/create-voice">
    POST /general/custom-voices
  </Card>
  <Card title="查询复刻任务" icon="flask" href="/api-reference/kling/get-voice">
    GET /general/custom-voices/{task_id}
  </Card>
  <Card title="列出已复刻音色" icon="flask" href="/api-reference/kling/list-voices">
    GET /general/custom-voices
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="能力总览与定价" icon="circle-info" href="/api-capabilities/kling/overview">
    模型清单、技术规格、计费规则
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/kling/video-generation">
    文 / 图 / Omni / 动作控制 / 数字人生成
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedream/overview.md

# Doubao Seedream 5.0 Pro 能力概览

> Doubao Seedream 5.0 Pro 的图片生成、参考图编辑、交互编辑、图层拆分与透明背景能力

Doubao Seedream 5.0 Pro（`doubao-seedream-5-0-pro-260628`）通过一个同步接口提供图片生成与编辑能力，兼容火山方舟图片生成 API 的请求与响应契约。普通模式返回一张基础图；图层拆分模式返回一张基础图和最多 16 个图层，`data` 最多包含 17 项。

<Note>
接口路径为 `POST /api/v3/images/generations`。请求完成后可直接从响应体读取 `url` 或 `b64_json`，无需创建任务或轮询状态。
</Note>

## 快速入口

<CardGroup cols={2}>
  <Card title="图片生成与编辑" icon="image" href="/api-capabilities/seedream/image-generation">
    查看公共参数、普通模式限制与请求示例
  </Card>
  <Card title="交互编辑" icon="crosshairs" href="/api-capabilities/seedream/interactive-editing">
    使用标注图、点坐标或框坐标指定编辑区域
  </Card>
  <Card title="图层拆分" icon="layer-group" href="/api-capabilities/seedream/layer-decomposition">
    自动或定向拆分基础图与透明 PNG 图层
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/seedream/create-image">
    查看并调试 `POST /api/v3/images/generations`
  </Card>
</CardGroup>

## 能力范围

<CardGroup cols={2}>
  <Card title="生成与参考图编辑" icon="images">
    支持文生图、单图编辑与最多 10 张参考图的多图融合
  </Card>
  <Card title="交互编辑" icon="pen-nib">
    支持上传标注图，以及在提示词中使用点坐标或框坐标
  </Card>
  <Card title="图层拆分" icon="layer-group">
    支持自动完整拆分、定向拆分与图层编辑
  </Card>
  <Card title="透明背景" icon="object-ungroup">
    符合条件的单图编辑可输出带透明通道的 PNG
  </Card>
</CardGroup>

| 能力 | 支持情况 | 说明 |
| --- | --- | --- |
| 文生图 | 支持 | 只传 `prompt`，返回一张基础图 |
| 单图编辑 | 支持 | 传入一张参考图和 `prompt` |
| 多参考图融合 | 支持 | 最多传入 10 张参考图，返回一张基础图 |
| 交互编辑 | 支持 | 标注图、`<point>` 点坐标和 `<bbox>` 框坐标 |
| 图层拆分 | 支持 | 一张基础图加最多 16 个图层，最多 17 项 |
| 透明背景 | 条件支持 | 必须是只输入一张图片且输出格式为 PNG 的编辑请求 |
| 组图 | 不支持 | 不支持 `sequential_image_generation` |
| 联网搜索 | 不支持 | 不支持 `tools` |
| 指定输出数量 | 不支持 | 不接受 `n`，普通模式固定返回一张基础图，图层数量由模型决定 |
| 流式输出 | 不支持 | `stream: true` 会返回参数错误；省略或传 `false` 均为同步调用 |

<Warning>
请勿携带 `n`、`sequential_image_generation`、`sequential_image_generation_options` 或 `tools`。这些参数不受支持。接口仅支持同步调用：`stream: true` 会返回参数错误，`stream: false` 可接受但不会改变同步行为。
</Warning>

## 模型与输出数量

| 模型 | 普通模式 | 图层拆分模式 |
| --- | --- | --- |
| `doubao-seedream-5-0-pro-260628` | 返回 **1 张基础图** | 返回 **1 张基础图 + 最多 16 个图层**，最多 17 项 |

普通模式要求非空 `prompt`；`image` 可省略，也可传单个字符串或最多 10 项的字符串数组。图层拆分模式必须且只能传一张图片，`prompt` 可省略。

## 技术规格

| 项目 | 规格 |
| --- | --- |
| 调用方式 | **同步** |
| Base URL | `https://api.looprouter.com` |
| 端点 | `POST /api/v3/images/generations` |
| 鉴权 | `Authorization: Bearer $LOOPROUTER_API_KEY` |
| 普通模式尺寸 | `1K` / `1.5K` / `2K`（默认 `2K`），或符合限制的显式 `宽x高` |
| 图层模式尺寸 | `auto`（默认）/ `1K` / `1.5K` / `2K`，不支持显式 `宽x高` |
| 输出格式 | `jpeg`（默认）或 `png` |
| 返回方式 | `url`（默认，链接 **24 小时**内有效）或 `b64_json` |
| 提示词优化 | `standard`（默认）或 `fast` |
| 水印 | 默认开启，可通过 `watermark: false` 关闭 |

### 透明背景条件

`background: "transparent"` 仅适用于同时满足以下条件的图片编辑请求：

- 传入且只传入 **1 张**图片；
- `output_format` 为 `png`。

其他请求默认使用 `background: "opaque"`。不符合条件的透明背景组合会返回参数错误。

## 快速调用

```bash 文生图（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一座建在云海之上的未来图书馆，清晨柔光，电影感构图",
    "size": "2K",
    "response_format": "url"
  }'
```

<Tip>
`response_format: "url"` 返回的图片链接在生成后 **24 小时**内有效，请在有效期内下载。希望直接保存图片数据时，可改用 `b64_json`。
</Tip>

## 常见问题

<AccordionGroup>
  <Accordion title="每次请求会返回多少项？">
    普通模式返回一张基础图。图层拆分模式返回一张基础图和最多 16 个图层，因此 `data` 最多包含 17 项。
  </Accordion>
  <Accordion title="普通编辑最多可以传几张参考图？">
    最多 10 张。单图可将 `image` 设为字符串；多图可设为字符串数组。
  </Accordion>
  <Accordion title="图片链接有效多久？">
    `response_format: "url"` 时，返回链接在图片生成后 **24 小时**内有效。`b64_json` 直接返回 Base64 图片数据，不依赖临时链接。
  </Accordion>
  <Accordion title="图层拆分是否使用独立端点？">
    不使用。仍调用 `POST /api/v3/images/generations`，并设置 `layer_decomposition: true`。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={2}>
  <Card title="图片生成与编辑" icon="image" href="/api-capabilities/seedream/image-generation">
    普通模式参数、输入限制与输出格式
  </Card>
  <Card title="图层拆分" icon="layer-group" href="/api-capabilities/seedream/layer-decomposition">
    图层模式参数、响应字段与完整示例
  </Card>
  <Card title="API Key" icon="key" href="https://console.looprouter.com/keys">
    在 LoopRouter 控制台创建 API Key
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    查看公开价格入口与余额说明
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedream/image-generation.md

# Doubao Seedream 5.0 Pro 图片生成与编辑

> Seedream 5.0 Pro 普通模式的公共参数、参考图限制、尺寸规格、输出格式与调用示例

Seedream 5.0 Pro 通过 `POST /api/v3/images/generations` 同步生成或编辑图片，兼容火山方舟图片生成 API 的请求与响应契约。文生图不传 `image`；单图编辑传一个字符串；多参考图融合传字符串数组。普通模式每次返回一张基础图。

<Warning>
本页介绍普通生成与编辑模式。请省略 `layer_decomposition`，或显式设为 `false`。如需一张基础图和多个透明图层，请参阅[图层拆分](/api-capabilities/seedream/layer-decomposition)。
</Warning>

## 创建图片

`POST /api/v3/images/generations`

<CodeGroup>

```bash 文生图（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一只戴宇航头盔的柴犬坐在月球表面，远处是地球，写实摄影",
    "size": "2K",
    "response_format": "url",
    "watermark": true
  }'
```

```python 文生图（Python · Ark SDK）
import os
from volcenginesdkarkruntime import Ark

client = Ark(
    base_url="https://api.looprouter.com/api/v3",
    api_key=os.environ["LOOPROUTER_API_KEY"],
)

result = client.images.generate(
    model="doubao-seedream-5-0-pro-260628",
    prompt="一只戴宇航头盔的柴犬坐在月球表面，远处是地球，写实摄影",
    size="2K",
    output_format="jpeg",
    response_format="url",
    watermark=True,
)

print(result.data[0].url)
```

```bash 单图编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把外套改成酒红色，其余内容保持不变",
    "image": "https://example.com/images/portrait.jpg",
    "size": "2K"
  }'
```

```bash 多参考图融合（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "让图1中的人物穿上图2中的服装，并采用图3的室内光线",
    "image": [
      "https://example.com/images/person.jpg",
      "https://example.com/images/outfit.jpg",
      "https://example.com/images/lighting.jpg"
    ],
    "size": "2K"
  }'
```

```bash 透明背景 PNG 编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "将主体改成蓝色陶瓷材质，保持透明背景",
    "image": "https://example.com/images/object-with-alpha.png",
    "output_format": "png",
    "background": "transparent",
    "size": "1.5K"
  }'
```

```bash b64_json 返回（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "极简产品海报，米白背景，柔和棚拍光线",
    "size": "1500x1000",
    "output_format": "png",
    "response_format": "b64_json",
    "optimize_prompt_options": { "mode": "fast" },
    "watermark": false
  }'
```

</CodeGroup>

<Note>
Python 示例使用 Ark SDK，并将 `base_url` 设置为 `https://api.looprouter.com/api/v3`。API Key 始终从 `LOOPROUTER_API_KEY` 环境变量读取。
</Note>

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 固定为 `doubao-seedream-5-0-pro-260628` |
| `prompt` | string | 是 | — | 非空提示词，支持模型提供的多语种输入 |
| `image` | string / string[] | 否 | — | 非空参考图 URL 或 Data URI；普通模式最多 10 张，数组项也不能为空 |
| `size` | string | 否 | `2K` | `1K` / `1.5K` / `2K`，或显式 `宽x高` |
| `optimize_prompt_options.mode` | string | 否 | `standard` | `standard` 或 `fast` |
| `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png` |
| `background` | string | 否 | `opaque` | `opaque` 或满足条件时使用 `transparent` |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json` |
| `layer_decomposition` | boolean | 否 | `false` | 普通模式省略或设为 `false` |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印 |
| `stream` | boolean | 否 | `false` | 仅接受 `false`，调用仍为同步；`true` 会返回参数错误 |

`size` 档位中的 `K` 匹配不区分大小写（例如 `2K` 与 `2k` 均可接受）；建议使用表中的规范写法。`optimize_prompt_options` 是对象，其中可选的 `mode` 仅接受 `standard` 或 `fast`。

### 参考图限制

`image` 可使用可公开访问的 URL，或 `data:image/<format>;base64,<data>` 形式的 Data URI。单张参考图必须满足：

- 格式为 **jpeg（也接受 jpg 别名）、png、webp、bmp、tiff（也接受 tif 别名）、gif、heic 或 heif**；
- 宽高比位于 **[1/16, 16]**；
- 宽和高均 **大于 14 px**；
- 文件大小 **不超过 30 MB**；
- 总像素位于 **[196, 36,000,000]**；
- 普通模式最多输入 **10 张**参考图。

## 尺寸规格

`size` 支持分辨率档位或显式宽高，两种写法不可混用。

### 分辨率档位

可选 `1K`、`1.5K`、`2K`，默认 `2K`。模型会结合提示词和参考图确定最终宽高。

### 显式 `宽x高`

例如 `2048x1024`。宽乘以高及宽高比必须同时满足：

- 总像素位于 **[921600, 4624220]**；
- 宽高比位于 **[1/16, 16]**。

| 示例 | 是否有效 | 说明 |
| --- | --- | --- |
| `2048x1024` | 是 | 2,097,152 像素，宽高比为 2 |
| `1500x1000` | 是 | 1,500,000 像素，宽高比为 1.5 |
| `512x512` | 否 | 262,144 像素，低于最小值 |

<Note>
显式宽高不要求按 8、16 或 64 的倍数对齐，只需满足总像素与宽高比范围。
</Note>

## 输出格式与透明背景

`output_format` 决定图片编码格式，`background` 决定背景行为。透明背景只在符合条件的单图编辑中可用。

| `output_format` | `background` | 支持情况 |
| --- | --- | --- |
| `jpeg` | `opaque` | 支持，默认组合 |
| `png` | `opaque` | 支持 |
| `png` | `transparent` | 条件支持：必须是只输入一张图片的编辑请求 |
| `jpeg` | `transparent` | 不支持 |

使用 `background: "transparent"` 时，必须传入且只传入一张图片，并将 `output_format` 设为 `png`。不满足条件的组合会返回参数错误。

## 返回方式

| `response_format` | `data[]` 字段 | 说明 |
| --- | --- | --- |
| `url` | `url` | 默认值；下载链接在图片生成后 **24 小时**内有效 |
| `b64_json` | `b64_json` | 直接返回 Base64 图片数据，不依赖临时链接 |

`response_format` 只改变图片数据的交付方式，不改变 `output_format`。例如 PNG 可通过 URL 返回，也可通过 `b64_json` 返回。

## 成功响应

普通模式的 `data` 包含一项。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 实际请求模型 |
| `created` | integer | Unix 时间戳（秒） |
| `data` | object[] | 普通模式包含一张基础图 |
| `usage` | object | 输入图片数、输出图片数和 token 统计 |

`data[]` 的字段如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `url` | string | `response_format: "url"` 时返回，**24 小时**内有效 |
| `b64_json` | string | `response_format: "b64_json"` 时返回 |
| `size` | string | 实际输出尺寸，格式为 `宽x高` |
| `output_format` | string | 实际输出格式，`jpeg` 或 `png` |

`usage` 包含：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `input_images` | integer | 输入参考图数量 |
| `generated_images` | integer | 生成的输出图片数量 |
| `output_tokens` | integer | 各输出图片像素总和除以 256 后取整 |
| `total_tokens` | integer | 此接口中与 `output_tokens` 一致 |

```json 成功响应
{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1785125529,
  "data": [
    {
      "url": "https://example.com/generated/output.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}
```

## 错误响应

失败时返回包含 `error.code` 与 `error.message` 的 JSON。`param`、`type` 仅在有明确值时出现。错误对象中的 `code` 存在且不为 `null`，或 `message` / `type` 非空时，接口都会将其识别为失败，而不会把该响应当作成功图片结果。

```json 参数错误
{
  "error": {
    "code": "InvalidParameter",
    "message": "The parameter `size` is invalid."
  }
}
```

| HTTP 状态码 | 常见错误 | 说明 |
| --- | --- | --- |
| 400 | `InvalidParameter` | 缺少必填参数、尺寸越界、图片不符合限制或参数组合无效 |
| 401 | `AuthenticationError` | API Key 缺失或无效 |
| 429 | `RateLimitExceeded` | 请求频率超出当前可用额度 |
| 5xx | 以 `error.code` 为准 | 服务端错误，错误码与消息按实际失败原因返回 |

<Warning>
Seedream 5.0 Pro 不接受 `n`、`sequential_image_generation`、`sequential_image_generation_options` 或 `tools`。接口仅支持同步调用：`stream: true` 会收到参数错误；省略 `stream` 或传 `false` 均保持同步。
</Warning>

## 相关文档

<CardGroup cols={2}>
  <Card title="交互编辑" icon="crosshairs" href="/api-capabilities/seedream/interactive-editing">
    标注图、点坐标与框坐标示例
  </Card>
  <Card title="图层拆分" icon="layer-group" href="/api-capabilities/seedream/layer-decomposition">
    自动拆分、定向拆分与图层响应字段
  </Card>
  <Card title="能力概览" icon="circle-info" href="/api-capabilities/seedream/overview">
    查看支持能力与模式差异
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/seedream/create-image">
    在线查看请求与响应结构
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedream/interactive-editing.md

# Doubao Seedream 5.0 Pro 交互编辑

> 使用标注图、点坐标与框坐标精确指定 Seedream 5.0 Pro 的图片编辑位置

交互编辑使用同一个同步端点 `POST /api/v3/images/generations`，兼容火山方舟图片生成 API 的请求与响应契约。上传待编辑图片，并通过标注图或提示词坐标指定目标位置，即可完成局部替换、删除或重绘。

<Info>
提示词坐标使用 **0..999** 的归一化坐标系：左上角为 `(0, 0)`，右下角为 `(999, 999)`。点坐标依次填写 `x y`，框坐标依次填写 `left top right bottom`。
</Info>

## 支持方式

<CardGroup cols={2}>
  <Card title="任意标记编辑" icon="pen">
    在图片上画线、画框或添加箭头，并在提示词中描述标记区域的修改目标
  </Card>
  <Card title="点坐标编辑" icon="location-dot">
    使用 `<point>x y</point>` 指定一个编辑位置
  </Card>
  <Card title="框坐标编辑" icon="vector-square">
    使用 `<bbox>left top right bottom</bbox>` 指定矩形编辑区域
  </Card>
  <Card title="普通输出控制" icon="sliders">
    可继续使用 `size`、`output_format`、`response_format` 与 `watermark`
  </Card>
</CardGroup>

## 任意标记编辑

<Steps>
  <Step title="标记目标区域">
    在原图上添加手绘线、方框或箭头等清晰标记。
  </Step>
  <Step title="上传标注图">
    将标注后的图片作为单张 `image` 输入。
  </Step>
  <Step title="描述修改目标">
    在 `prompt` 中说明标记区域及期望结果，例如“把红色箭头指向的杯子改成玻璃材质”。
  </Step>
</Steps>

## 请求示例

<CodeGroup>

```bash 标注图交互编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把红色箭头指向的杯子改成透明玻璃材质，移除图片中的箭头标记",
    "image": "https://example.com/images/annotated-cup.png",
    "size": "2K",
    "output_format": "png"
  }'
```

```bash 点坐标编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把图1<point>520 460</point>位置换成皇冠",
    "image": "https://example.com/images/portrait.jpg",
    "size": "2K"
  }'
```

```bash 框坐标编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把图1<bbox>120 180 640 760</bbox>区域替换成花园",
    "image": "https://example.com/images/courtyard.jpg",
    "size": "2K"
  }'
```

</CodeGroup>

## 坐标规则

| 标签 | 格式 | 坐标范围 | 含义 |
| --- | --- | --- | --- |
| `<point>` | `<point>x y</point>` | 每个值为 **0..999** | 指定一个点 |
| `<bbox>` | `<bbox>left top right bottom</bbox>` | 每个值为 **0..999** | 指定矩形左上角与右下角 |

<Tip>
坐标按图片的相对位置计算，与输入图片的实际像素尺寸无关。例如 `(500, 500)` 大致位于图片中心。
</Tip>

<Warning>
交互编辑提示词的坐标范围是 **0..999**。图层拆分响应中的 `bounding_box.normalized` 使用另一套 **0..1000** 范围，请勿混用。
</Warning>

## 输入与输出

交互编辑属于普通单图编辑，因此必须传入一张非空图片。输入图支持 jpeg（含 jpg 别名）、png、webp、bmp、tiff（含 tif 别名）、gif、heic、heif；单张不超过 30 MB，宽和高均大于 14 px，总像素位于 [196, 36,000,000]，宽高比位于 [1/16, 16]。普通响应的 `data` 包含一张基础图。完整返回格式请参阅[图片生成与编辑](/api-capabilities/seedream/image-generation)。

当 `response_format: "url"` 时，图片链接在生成后 **24 小时**内有效；使用 `response_format: "b64_json"` 时，图片数据位于 `data[0].b64_json`。

## 相关文档

<CardGroup cols={2}>
  <Card title="图片生成与编辑" icon="image" href="/api-capabilities/seedream/image-generation">
    查看普通模式参数与输入图片限制
  </Card>
  <Card title="图层拆分" icon="layer-group" href="/api-capabilities/seedream/layer-decomposition">
    查看图层元数据与 0..1000 响应坐标
  </Card>
  <Card title="能力概览" icon="circle-info" href="/api-capabilities/seedream/overview">
    查看模型的完整能力范围
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/seedream/create-image">
    查看统一端点的请求结构
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-capabilities/seedream/layer-decomposition.md

# Doubao Seedream 5.0 Pro 图层拆分

> 使用 Seedream 5.0 Pro 自动拆分、定向拆分或编辑图片图层，并读取图层位置元数据

图层拆分仍使用 `POST /api/v3/images/generations`，兼容火山方舟图片生成 API 的请求与响应契约，并通过 `layer_decomposition: true` 开启。响应包含一张基础图和最多 16 个图层，`data` 最多包含 17 项。

<CardGroup cols={2}>
  <Card title="自动完整拆分" icon="wand-magic-sparkles">
    不传 `prompt`，自动识别并拆分图片中的主要元素
  </Card>
  <Card title="定向拆分" icon="bullseye">
    传入 `prompt`，描述希望拆出的对象或图层
  </Card>
  <Card title="图层编辑" icon="pen-to-square">
    传入 `prompt`，描述需要修改的图层及编辑目标
  </Card>
  <Card title="完整图层结果" icon="layer-group">
    返回基础图、透明 PNG 图层及每层的位置和说明
  </Card>
</CardGroup>

## 输入限制

| 项目 | 限制 |
| --- | --- |
| `image` | **必须且只能输入 1 张**，可传字符串或仅含一项的字符串数组 |
| 输入格式 | **png 或 jpeg**（也接受 jpg 别名） |
| 文件大小 | **不超过 30 MB** |
| 输入宽高 | 宽和高均 **大于 14 px** |
| 输入总像素 | **[262144, 36000000]** |
| 输入宽高比 | **[1/16, 16]** |
| `prompt` | 可选；省略时自动完整拆分，填写时用于定向拆分或图层编辑 |
| `size` | `auto`（默认）、`1K`、`1.5K`、`2K` |
| 显式 `宽x高` | **不支持** |
| 最大输出数 | **17 项**：1 张基础图 + 最多 16 个图层 |

`size: "auto"` 会保持原图宽高比：原图位于支持的 1K–2K 范围时尽量保持原分辨率，低于范围时上采样，高于范围时限制到支持的上限。

<Warning>
图层拆分采用完整结果语义：任一图层生成失败，整个请求都会失败，不返回部分成功结果。
</Warning>

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 固定为 `doubao-seedream-5-0-pro-260628` |
| `image` | string / string[] | 是 | — | 一张非空的 png 或 jpeg 图片；也接受 jpg 别名 |
| `layer_decomposition` | boolean | 是 | — | 必须为 `true` |
| `prompt` | string | 否 | — | 省略时自动完整拆分；填写时定向拆分或编辑 |
| `size` | string | 否 | `auto` | `auto` / `1K` / `1.5K` / `2K` |
| `optimize_prompt_options.mode` | string | 否 | `standard` | `standard` 或 `fast` |
| `output_format` | string | 否 | `jpeg` | 基础图格式：`jpeg` 或 `png` |
| `background` | string | 否 | `opaque` | `opaque` 或 `transparent`；传 `transparent` 时必须同时传 `output_format: "png"` |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json` |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印 |
| `stream` | boolean | 否 | `false` | 仅接受 `false`，调用仍为同步；`true` 会返回参数错误 |

`size` 的枚举匹配不区分大小写，建议使用表中的规范写法。图层数量由模型决定，不能传 `n`；也不能传 `sequential_image_generation`、`sequential_image_generation_options` 或 `tools`。接口仅支持同步调用，`stream: true` 会返回参数错误，`stream: false` 可接受但不会改变同步行为。

## 请求示例

<CodeGroup>

```bash 自动完整图层拆分（不传 prompt）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "image": "https://example.com/images/poster.png",
    "layer_decomposition": true,
    "size": "auto",
    "response_format": "url"
  }'
```

```bash 定向图层拆分（传入 prompt）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "分别拆出标题文字、前景人物和背景装饰",
    "image": "https://example.com/images/poster.png",
    "layer_decomposition": true,
    "size": "2K",
    "output_format": "jpeg"
  }'
```

```bash 图层编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "将标题文字改为金色立体字，并保留其他可编辑图层",
    "image": "https://example.com/images/poster.png",
    "layer_decomposition": true,
    "size": "1.5K",
    "output_format": "png"
  }'
```

</CodeGroup>

## 输出规则

| 输出项 | 格式 | 位置 |
| --- | --- | --- |
| 基础图 | 由 `output_format` 决定，默认 jpeg | `data[0]`，`z_index: 0` |
| 拆分图层 | **始终为带透明通道的 PNG** | 后续 `data[]`，`z_index` 从 1 递增 |

当 `response_format: "url"` 时，每个输出项使用 `url`，链接在生成后 **24 小时**内有效；当值为 `b64_json` 时，每个输出项使用 `b64_json`。

## 响应字段

顶层响应包含 `model`、`created`、`data` 与 `usage`。`data[]` 使用统一的输出项结构：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `url` | string | `response_format: "url"` 时返回 |
| `b64_json` | string | `response_format: "b64_json"` 时返回 |
| `size` | string | 当前输出项的实际尺寸，格式为 `宽x高` |
| `output_format` | string | 基础图由请求决定；拆分图层始终为 `png` |
| `z_index` | integer | 基础图为 0，后续图层从 1 递增 |
| `bounding_box.absolute` | integer[4] | `[left, top, right, bottom]`，相对于基础输出图的像素坐标 |
| `bounding_box.normalized` | integer[4] | `[left, top, right, bottom]`，每个值位于 **0..1000** |
| `name` | string | 图层名称 |
| `description` | string | 图层内容说明 |

<Warning>
两个坐标范围不可合并：交互编辑提示词中的 `<point>` 与 `<bbox>` 使用 **0..999**；图层响应的 `bounding_box.normalized` 使用 **0..1000**。
</Warning>

`usage` 包含 `input_images`、`generated_images`、`output_tokens` 和 `total_tokens`。`output_tokens` 为各输出图片像素总和除以 256 后取整；此接口中 `total_tokens` 与 `output_tokens` 一致。

```json 图层拆分成功响应
{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1784696685,
  "data": [
    {
      "url": "https://example.com/generated/base.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://example.com/generated/layer-1.png",
      "size": "1273x265",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [383, 120, 1655, 384],
        "normalized": [187, 59, 808, 188]
      },
      "name": "标题文字",
      "description": "黄色大号衬线字体的标题文字"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 2,
    "output_tokens": 17701,
    "total_tokens": 17701
  }
}
```

<Note>
基础图通常不包含 `bounding_box`、`name` 与 `description`；这些字段用于描述后续拆分图层。
</Note>

## 相关文档

<CardGroup cols={2}>
  <Card title="图片生成与编辑" icon="image" href="/api-capabilities/seedream/image-generation">
    查看普通模式参数与透明背景条件
  </Card>
  <Card title="交互编辑" icon="crosshairs" href="/api-capabilities/seedream/interactive-editing">
    查看提示词坐标格式与示例
  </Card>
  <Card title="能力概览" icon="circle-info" href="/api-capabilities/seedream/overview">
    查看普通模式与图层模式差异
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/seedream/create-image">
    查看统一端点的条件请求结构
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/api-reference/create-video-task.md

# 创建视频生成任务

`POST /api/v3/contents/generations/tasks`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/get-video-task.md

# 查询视频生成任务

`GET /api/v3/contents/generations/tasks/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/wan3/create-video-task.md

# 创建视频生成任务（万相 3.0）

`POST /api/v1/services/aigc/video-generation/video-synthesis`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/wan3/get-video-task.md

# 查询视频生成任务（万相 3.0）

`GET /api/v1/tasks/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax/create-video-task.md

# 创建视频生成任务

`POST /v2/video_generation`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax/get-video-task.md

# 查询视频生成任务

`GET /v2/query/video_generation/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax/list-video-tasks.md

# 任务列表

`GET /v2/query/video_generation`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax/delete-video-task.md

# 取消 / 删除任务

`DELETE /v2/video_generation/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax/h3-context-ir.md

# 提示增强 Context-IR

`POST /v2/h3_context_ir`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax/video-regeneration.md

# 视频再生 768P → 2K

`POST /v2/video_regeneration`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax-special/create-video-task.md

# 创建特惠视频任务

`POST /special/v2/video_generation`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax-special/get-video-task.md

# 查询特惠视频任务

`GET /special/v2/query/video_generation/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax-special/list-video-tasks.md

# 特惠任务列表

`GET /special/v2/query/video_generation`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax-special/h3-context-ir.md

# 特惠提示词增强

`POST /special/v2/h3_context_ir`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax-special/video-regeneration.md

# 特惠视频再生成

`POST /special/v2/video_regeneration`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/minimax-special/delete-video-task.md

# 删除已结束的特惠任务

`DELETE /special/v2/video_generation/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/text-to-video.md

# 文生视频（可灵 3.0）

`POST /text-to-video/{model}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/image-to-video.md

# 图生视频（可灵 3.0）

`POST /image-to-video/{model}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/omni-video.md

# Omni 多模态生成（可灵 3.0）

`POST /omni-video/{model}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/motion-control.md

# 动作控制（可灵 3.0）

`POST /motion-control/{model}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/avatar.md

# 数字人提交（可灵 3.0）

`POST /videos/avatar/image2video`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/get-avatar.md

# 数字人查询（可灵 3.0）

`GET /videos/avatar/image2video/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/create-voice.md

# 声音复刻提交（可灵 3.0）

`POST /general/custom-voices`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/get-voice.md

# 声音复刻查询（可灵 3.0）

`GET /general/custom-voices/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/list-voices.md

# 声音复刻列表（可灵 3.0）

`GET /general/custom-voices`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/create-custom-element.md

# 创建自定义主体（可灵 3.0）

`POST /general/advanced-custom-elements`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/get-custom-element.md

# 查询自定义主体（可灵 3.0）

`GET /general/advanced-custom-elements/{task_id}`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/list-preset-elements.md

# 查询官方预置主体（可灵 3.0）

`GET /general/advanced-presets-elements`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/kling/list-tasks.md

# 任务查询（可灵 3.0）

`GET /tasks`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/api-reference/seedream/create-image.md

# 创建图像生成请求

`POST /api/v3/images/generations`

本页面由 OpenAPI 规范自动生成。完整的请求参数、响应结构与示例请见:
https://docs.looprouter.com/openapi.yaml

---

URL: https://docs.looprouter.com/video-processing/overview.md

# 视频处理总览

> 对已有视频做后期再处理：智能插帧、字幕擦除、画质增强、漫剧转绘。完全兼容火山云官方 API 格式，换域名与密钥即可接入。

视频处理是一组**对已有视频做后期再处理**的异步接口，全面对齐**火山云官方 API 格式**——如果你已经在使用火山云的对应能力，只需把域名与密钥换成 LoopRouter 签发的即可无缝迁移；请求路径、参数与响应结构保持一致。

能力分为两个系列：

## 火山云 AI MediaKit 系列

使用 **API Key**（`sk-` 令牌）鉴权，Base URL 指向 `https://api.looprouter.com/api/aimediakit`。

<CardGroup cols={2}>
  <Card title="智能插帧" icon="film" href="/video-processing/aimediakit/frame-interpolation">
    把视频补帧到更高帧率（最高 120 fps），让运动画面更顺滑流畅
  </Card>
  <Card title="字幕擦除" icon="closed-captioning" href="/video-processing/aimediakit/subtitle-erasure-pro">
    精细擦除画面中的硬字幕 / 文字，支持指定区域、时间窗与字幕过滤
  </Card>
  <Card title="画质增强（标准版 / 专业版）" icon="sparkles" href="/video-processing/aimediakit/enhance-video">
    提升清晰度、色彩与码率表现，支持最高 8K 输出与专业版 10/12/16 位深
  </Card>
  <Card title="画质增强（大模型版）" icon="microchip-ai" href="/video-processing/aimediakit/enhance-video-generative">
    大模型驱动的生成式超分增强，最高 2K 输出
  </Card>
</CardGroup>

## 火山云 VOD 系列

使用 **AK/SK** 鉴权（在控制台获取，配合火山官方 SDK / 签名方式），Base URL 指向 `https://api.looprouter.com/api/vod`。

<CardGroup cols={2}>
  <Card title="AI 漫剧转绘" icon="palette" href="/video-processing/vod/comic-style-transfer">
    把真人 / 实拍视频整体转绘为漫画风格成片，支持 480p / 720p / 1080p 输出
  </Card>
  <Card title="VOD 接入说明" icon="key" href="/video-processing/vod/overview">
    AK/SK 获取、官方 SDK 配置与统一响应结构
  </Card>
</CardGroup>

## 计费与结算

所有视频处理能力均采用**按实际用量后付费**模式（与火山官方一致）：

- 任务**成功**后，按**实际输出**（输出时长 × 输出分辨率档位）计费，从账户余额中扣除；
- 任务**失败不收费**；
- 提交时不预扣、不冻结额度。

<Note>
各能力按成片**输出时长**（¥/分钟）并结合**输出分辨率档位**分档计费。具体价格请见 [控制台](https://console.looprouter.com) 或联系商务。
</Note>

## 通用调用流程

<Steps>
  <Step title="准备视频源">
    提供一个公网可直接访问的视频链接（`http(s)`，最长 1024 字符）。
  </Step>
  <Step title="提交处理任务">
    调用对应能力的提交接口。接口立即返回任务 ID，**不会**同步返回成片。
  </Step>
  <Step title="轮询任务状态">
    用任务 ID 调用查询接口轮询，直至任务成功或失败。建议每 5–15 秒轮询一次。
  </Step>
  <Step title="下载成片">
    任务成功后，响应中的视频链接即为成片下载地址。
  </Step>
</Steps>

<Warning>
成片链接为**临时链接**，约 **2 小时**后失效。请在任务成功后**尽快下载**并转存到你自己的存储。下载时无需携带鉴权请求头。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="AI MediaKit 接入说明" icon="rocket" href="/video-processing/aimediakit/overview">
    Base URL、鉴权、统一响应结构与错误码
  </Card>
  <Card title="常见问题" icon="circle-question" href="/video-processing/faq">
    视频来源限制、计费时机、失败退费、参数排错
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/video-processing/aimediakit/overview.md

# AI MediaKit 接入说明

> 火山云 AI MediaKit 系列能力的 Base URL、API Key 鉴权、统一响应结构与错误码。

AI MediaKit 系列提供**智能插帧、字幕擦除、画质增强**三类视频再处理能力，接口格式与火山云官方 AI MediaKit 完全一致——若你已有基于官方 API 的接入代码或 SDK，只需**替换 Base URL 与 API Key** 即可直接使用。

## 基础信息

- **Base URL**：

  ```
  https://api.looprouter.com/api/aimediakit
  ```

  完整接口路径为 Base URL + `/api/v1/...`（与官方一致，官方 SDK 会自动拼接）。

- **鉴权**：所有接口都需在请求头携带 API Key：

  ```
  Authorization: Bearer sk-你的APIKey
  Content-Type: application/json
  ```

  在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建 `sk-` 开头的 API Key。

- **调用模式**：异步。提交任务立即返回 `task_id`，需轮询 [任务查询接口](/video-processing/aimediakit/get-task) 获取结果。

## 能力一览

| 能力 | 接口 |
| --- | --- |
| [智能插帧](/video-processing/aimediakit/frame-interpolation) | `POST /api/v1/tools/video-frame-interpolation` |
| [字幕擦除](/video-processing/aimediakit/subtitle-erasure-pro) | `POST /api/v1/tools/erase-video-subtitle-pro` |
| [画质增强（标准版 / 专业版）](/video-processing/aimediakit/enhance-video) | `POST /api/v1/tools/enhance-video` |
| [画质增强（大模型版）](/video-processing/aimediakit/enhance-video-generative) | `POST /api/v1/tools/enhance-video-generative` |
| [任务查询（通用）](/video-processing/aimediakit/get-task) | `GET /api/v1/tasks/{task_id}` |

## 统一响应结构

### 提交成功（受理）

所有提交接口（`POST /api/v1/tools/*`）成功受理后同步返回：

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。

### 请求失败

```json
{
  "success": false,
  "task_id": "",
  "error": {
    "code": "InvalidParameter",
    "type": "BadRequest",
    "message": "frame_interpolation.fps must be between 15 and 120"
  },
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

### 错误码

| HTTP | `error.code` | `error.type` | 说明 |
| --- | --- | --- | --- |
| 400 | `InvalidParameter` | `BadRequest` | 请求参数非法，`message` 会说明具体原因 |
| 401 | `Unauthorized` | `Unauthorized` | API Key 缺失或无效 |
| 403 | `QuotaExceeded` | `Forbidden` | 账户余额不足或超出可用额度 |
| 404 | `NotFound` | `NotFound` | 任务不存在 |
| 429 | `TooManyRequests` | `Throttling` | 请求过于频繁或未完成任务数超上限 |
| 503 | `ServiceUnavailable` | `ServiceUnavailable` | 服务暂不可用 |
| 其它 5xx | `InternalError` | `InternalError` | 内部错误，请稍后重试 |

## 视频源要求

所有能力的 `video_url` 均要求：

- 公网可直接访问的 `http(s)` 链接；
- 最长 **1024** 字符；
- 不支持 base64 内联数据。

## 成片链接有效期

<Warning>
任务成功后返回的成片 `video_url` 为**临时链接**，约 **2 小时**后失效。请尽快下载并转存到你自己的存储。下载时无需携带 `Authorization` 请求头。
</Warning>

## 计费

按**实际用量后付费**：任务成功后按**实际输出时长与输出分辨率档位**计费；任务失败**不收费**。详见 [视频处理总览](/video-processing/overview#计费与结算)。

---

URL: https://docs.looprouter.com/video-processing/aimediakit/frame-interpolation.md

# 智能插帧

> 把视频补帧到更高帧率（最高 120 fps），让运动画面更顺滑流畅。兼容火山云 AI MediaKit 官方格式。

智能插帧通过 AI 补帧把视频提升到更高帧率，让运动画面更顺滑流畅，适合游戏录屏、体育 / 动作素材、动画提帧等场景。

```
POST /api/aimediakit/api/v1/tools/video-frame-interpolation
```

## 请求体

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `video_url` | string | 是 | 源视频公网链接（`http(s)`，最长 1024 字符） |
| `fps` | number | 是 | 目标帧率。取值范围 `[15, 120]`，且必须**大于源视频帧率**、**不超过源帧率的 4 倍**。支持小数帧率（如 `59.94`） |

<Note>
`fps` 相对源帧率的约束在任务处理阶段校验：目标帧率不高于源帧率、或超过源帧率 4 倍时任务会失败（失败不收费）。提交前建议先确认源视频帧率。
</Note>

## 示例

<CodeGroup>

```bash cURL
curl -X POST "https://api.looprouter.com/api/aimediakit/api/v1/tools/video-frame-interpolation" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "fps": 60
  }'
```

```python Python
import requests

resp = requests.post(
    "https://api.looprouter.com/api/aimediakit/api/v1/tools/video-frame-interpolation",
    headers={"Authorization": "Bearer sk-你的APIKey"},
    json={
        "video_url": "https://example.com/source.mp4",
        "fps": 60,
    },
)
print(resp.json())  # {"success": true, "task_id": "...", "request_id": "..."}
```

</CodeGroup>

## 响应

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。任务成功后，结果中的 `resolution`、`fps` 会回填实际输出的分辨率档位与帧率。

## 相关页面

<CardGroup cols={2}>
  <Card title="任务查询" icon="magnifying-glass" href="/video-processing/aimediakit/get-task">
    轮询任务状态、获取成片链接
  </Card>
  <Card title="接入说明" icon="rocket" href="/video-processing/aimediakit/overview">
    鉴权、统一响应结构与错误码
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/video-processing/aimediakit/subtitle-erasure-pro.md

# 字幕擦除

> 精细擦除视频画面中的硬字幕与文字，支持指定擦除区域、时间窗与字幕高度过滤。兼容火山云 AI MediaKit 官方格式。

字幕擦除自动识别并擦除视频画面中**烧录在画面上的硬字幕、文字**，还原干净画面，支持精细控制：限定擦除区域、只处理指定时间段、按文字高度过滤，常用于素材二次创作、多语言重制、去水印等场景。

```
POST /api/aimediakit/api/v1/tools/erase-video-subtitle-pro
```

## 请求体

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `video_url` | string | 是 | — | 源视频公网链接（`http(s)`，最长 1024 字符） |
| `model_version` | string | 否 | `v4` | 模型版本，可选 `v4` / `v5` |
| `mode` | string | 否 | `subtitle` | 擦除模式：`subtitle`（字幕）/ `text`（画面文字） |
| `output_encode_mode` | string | 否 | `quality` | 输出编码取向：`quality`（画质优先）/ `size`（体积优先） |
| `erase_ratio_location` | array | 否 | — | 擦除区域列表（归一化矩形），不传则全画面自动识别，见下 |
| `time_segment_filter` | object | 否 | 全片 | 时间窗过滤，见下 |
| `subtitle_filter` | object | 否 | — | 字幕高度 / 位置过滤，见下 |

### `erase_ratio_location[]` 元素

坐标为 **0..1 归一化**比例（相对画面宽高），`bottom_right` 必须严格大于 `top_left`：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `top_left_x` | number | 矩形左上角 x（0..1） |
| `top_left_y` | number | 矩形左上角 y（0..1） |
| `bottom_right_x` | number | 矩形右下角 x（0..1） |
| `bottom_right_y` | number | 矩形右下角 y（0..1） |

### `time_segment_filter`

| 字段 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `mode` | string | `all` | `all`（全片处理）/ `selected`（仅处理选中时间段）/ `skip`（跳过选中时间段）。`selected` 时 `segments` 必填且非空 |
| `segments` | array | — | 时间窗数组，元素为 `{start_time, end_time}`（单位：秒，要求 `end_time` 大于 `start_time`） |

### `subtitle_filter`

均为可选，缺省不过滤：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `min_text_height_ratio` | number | 最小文字高度占比，低于此高度的文字不擦除 |
| `max_text_height_ratio` | number | 最大文字高度占比，高于此高度的文字不擦除 |
| `center_offset_ratio` | number | 相对画面中心的偏移占比过滤 |

## 示例

<CodeGroup>

```bash cURL
curl -X POST "https://api.looprouter.com/api/aimediakit/api/v1/tools/erase-video-subtitle-pro" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "model_version": "v4",
    "mode": "subtitle",
    "output_encode_mode": "quality",
    "erase_ratio_location": [
      { "top_left_x": 0.1, "top_left_y": 0.82, "bottom_right_x": 0.9, "bottom_right_y": 0.95 }
    ],
    "time_segment_filter": {
      "mode": "selected",
      "segments": [
        { "start_time": 0.0, "end_time": 12.5 },
        { "start_time": 30.0, "end_time": 45.0 }
      ]
    },
    "subtitle_filter": {
      "min_text_height_ratio": 0.02,
      "max_text_height_ratio": 0.15,
      "center_offset_ratio": 0.3
    }
  }'
```

```python Python
import requests

resp = requests.post(
    "https://api.looprouter.com/api/aimediakit/api/v1/tools/erase-video-subtitle-pro",
    headers={"Authorization": "Bearer sk-你的APIKey"},
    json={
        "video_url": "https://example.com/source.mp4",
        "erase_ratio_location": [
            {"top_left_x": 0.1, "top_left_y": 0.82,
             "bottom_right_x": 0.9, "bottom_right_y": 0.95},
        ],
    },
)
print(resp.json())  # {"success": true, "task_id": "...", "request_id": "..."}
```

</CodeGroup>

<Tip>
最简调用只需 `video_url` 一个字段——模型版本、模式、编码取向都有默认值，且默认全画面、全片自动识别擦除。
</Tip>

## 响应

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。字幕擦除任务成功后，结果包含成片 `video_url` 与 `duration`（不含 `resolution` / `fps` 字段，输出保持源视频规格）。

## 相关页面

<CardGroup cols={2}>
  <Card title="任务查询" icon="magnifying-glass" href="/video-processing/aimediakit/get-task">
    轮询任务状态、获取成片链接
  </Card>
  <Card title="接入说明" icon="rocket" href="/video-processing/aimediakit/overview">
    鉴权、统一响应结构与错误码
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/video-processing/aimediakit/enhance-video.md

# 画质增强（标准版 / 专业版）

> 提升视频清晰度、色彩与码率表现，最高 8K 输出，专业版支持 10/12/16 位深。兼容火山云 AI MediaKit 官方格式。

画质增强对原片做整体画质提升——优化清晰度、细节与色彩表现，并可指定输出分辨率、码率、帧率。标准版与专业版**共用同一接口**，由 `tool_version` 区分（缺省即标准版）；专业版额外支持高位深输出。

```
POST /api/aimediakit/api/v1/tools/enhance-video
```

## 请求体

| 字段 | 类型 | 必填 | 默认 | 适用版本 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `video_url` | string | 是 | — | 全部 | 源视频公网链接（`http(s)`，最长 1024 字符） |
| `tool_version` | string | 否 | `standard` | — | `standard`(标准版) / `professional`(专业版) |
| `scene` | string | 否 | — | **仅标准版** | 增强场景 |
| `enhance_style` | string | 否 | — | 标准版 + 专业版 | 增强风格 |
| `resolution` | string | 是 | — | 全部 | 输出分辨率档位：`720p` / `1080p` / `2k` / `4k` / `8k`（实际可用档位以账户开通为准） |
| `bitrate_level` | string | 否 | — | 全部 | 码率档位：`low` / `medium` / `high`。与 `bitrate` 二选一 |
| `bitrate` | int | 否 | — | 全部 | 目标码率（kbps），范围 `[10, 150000]`。与 `bitrate_level` 二选一 |
| `fps` | number | 否 | — | 全部 | 目标帧率，范围 `[15, 120]` |
| `bit_depth` | int | 否 | — | **仅专业版** | 输出位深：`8` / `10` / `12` / `16` |

<Warning>
- `bitrate` 与 `bitrate_level` **至多提供其一**，同时提供会返回参数错误。
- `scene` 仅标准版接受；`bit_depth` 仅专业版接受——版本不匹配会返回参数错误。
</Warning>

## 示例

### 专业版

```bash cURL
curl -X POST "https://api.looprouter.com/api/aimediakit/api/v1/tools/enhance-video" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "tool_version": "professional",
    "enhance_style": "sharp",
    "resolution": "1080p",
    "bitrate": 8000,
    "fps": 30,
    "bit_depth": 10
  }'
```

### 标准版

```bash cURL
curl -X POST "https://api.looprouter.com/api/aimediakit/api/v1/tools/enhance-video" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "tool_version": "standard",
    "scene": "film",
    "enhance_style": "natural",
    "resolution": "720p",
    "bitrate_level": "high",
    "fps": 25
  }'
```

## 响应

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。任务成功后，结果中的 `tool_version` 会回填 `standard` / `professional`，`resolution`、`fps` 回填实际输出规格。

## 相关页面

<CardGroup cols={2}>
  <Card title="画质增强（大模型版）" icon="microchip-ai" href="/video-processing/aimediakit/enhance-video-generative">
    大模型驱动的生成式超分增强
  </Card>
  <Card title="任务查询" icon="magnifying-glass" href="/video-processing/aimediakit/get-task">
    轮询任务状态、获取成片链接
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/video-processing/aimediakit/enhance-video-generative.md

# 画质增强（大模型版）

> 大模型驱动的生成式超分增强，最高 2K 输出。兼容火山云 AI MediaKit 官方格式。

画质增强大模型版使用生成式大模型做超分与画质重建，对低清、老旧素材的修复效果更强。仅支持分辨率、码率、帧率三类输出参数（无 `tool_version` / `scene` / `enhance_style` / `bit_depth`，误传会被忽略）。

```
POST /api/aimediakit/api/v1/tools/enhance-video-generative
```

## 请求体

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `video_url` | string | 是 | 源视频公网链接（`http(s)`，最长 1024 字符） |
| `resolution` | string | 是 | 输出分辨率档位：`720p` / `1080p` / `2k`（实际可用档位以账户开通为准） |
| `bitrate_level` | string | 否 | 码率档位：`low` / `medium` / `high`。与 `bitrate` 二选一 |
| `bitrate` | int | 否 | 目标码率（kbps），范围 `[10, 150000]`。与 `bitrate_level` 二选一 |
| `fps` | number | 否 | 目标帧率，范围 `[15, 120]` |

## 示例

<CodeGroup>

```bash cURL
curl -X POST "https://api.looprouter.com/api/aimediakit/api/v1/tools/enhance-video-generative" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "video_url": "https://example.com/source.mp4",
    "resolution": "2k",
    "bitrate_level": "high",
    "fps": 30
  }'
```

```python Python
import requests

resp = requests.post(
    "https://api.looprouter.com/api/aimediakit/api/v1/tools/enhance-video-generative",
    headers={"Authorization": "Bearer sk-你的APIKey"},
    json={
        "video_url": "https://example.com/source.mp4",
        "resolution": "2k",
    },
)
print(resp.json())  # {"success": true, "task_id": "...", "request_id": "..."}
```

</CodeGroup>

## 响应

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

拿到 `task_id` 后轮询 [任务查询接口](/video-processing/aimediakit/get-task)。大模型版任务成功后的结果包含 `video_url`、`duration`、`resolution`、`fps`（**不含** `tool_version` 字段）。

## 相关页面

<CardGroup cols={2}>
  <Card title="画质增强（标准版 / 专业版）" icon="sparkles" href="/video-processing/aimediakit/enhance-video">
    传统增强管线，最高 8K 输出与高位深支持
  </Card>
  <Card title="任务查询" icon="magnifying-glass" href="/video-processing/aimediakit/get-task">
    轮询任务状态、获取成片链接
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/video-processing/aimediakit/get-task.md

# 任务查询

> 查询 AI MediaKit 系列任务的状态与结果：进行中、成功（成片链接）、失败（错误原因）。

AI MediaKit 系列所有能力共用同一个任务查询接口。用提交时返回的 `task_id` 轮询，建议每 5–15 秒一次。

```
GET /api/aimediakit/api/v1/tasks/{task_id}
```

```bash cURL
curl "https://api.looprouter.com/api/aimediakit/api/v1/tasks/vg_9f8c1e2b7a6d4f30" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

## 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `success` | bool | 本次查询请求是否成功（不代表任务成败） |
| `task_id` | string | 任务 ID |
| `task_type` | string | 能力标识：`video-frame-interpolation` / `erase-video-subtitle-pro` / `enhance-video` / `enhance-video-generative` |
| `status` | string | 任务状态：`running`（进行中）/ `completed`（成功）/ `failed`（失败） |
| `result` | object | 任务成功时的结果，见下；其余状态不返回 |
| `error` | object | 任务失败时的错误信息，见下；其余状态不返回 |
| `created_at` | number | 任务创建时间（Unix 秒） |
| `finished_at` | number | 任务结束时间（Unix 秒），未结束不返回 |
| `request_id` | string | 本次请求 ID |

### `result` 对象（任务成功时）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `video_url` | string | 成片下载链接（**临时链接，约 2 小时后失效**，请尽快下载） |
| `resolution` | string | 实际输出分辨率档位（`240p`–`8k`）。插帧 / 画质增强返回；字幕擦除不返回 |
| `duration` | number | 成片时长（秒） |
| `fps` | number | 实际输出帧率。插帧 / 画质增强返回；字幕擦除不返回 |
| `tool_version` | string | 仅画质增强标准版 / 专业版返回（`standard` / `professional`） |

### `error` 对象（任务失败时）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 固定 `TaskFailed` |
| `type` | string | 固定 `TaskError` |
| `message` | string | 失败原因说明 |

<Note>
计费按**实际用量后付费**：任务成功后才按实际输出计费，任务失败**不收费**。
</Note>

## 响应示例

### 进行中

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "task_type": "enhance-video",
  "status": "running",
  "created_at": 1756699200,
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

### 成功

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "task_type": "enhance-video",
  "status": "completed",
  "result": {
    "video_url": "https://…/out.mp4?…",
    "resolution": "1080p",
    "duration": 12.5,
    "fps": 30,
    "tool_version": "professional"
  },
  "created_at": 1756699200,
  "finished_at": 1756699320,
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

### 失败

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "task_type": "erase-video-subtitle-pro",
  "status": "failed",
  "error": {
    "code": "TaskFailed",
    "type": "TaskError",
    "message": "source video download failed"
  },
  "created_at": 1756699200,
  "finished_at": 1756699280,
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

## 完整调用流程（Python）

提交任务 → 轮询直到完成 → 下载成片，切换能力只需改提交接口与参数：

```python Python
import time
import requests

BASE = "https://api.looprouter.com/api/aimediakit"
HEADERS = {"Authorization": "Bearer sk-你的APIKey"}

# 1. 提交任务（以智能插帧为例）
submit = requests.post(
    f"{BASE}/api/v1/tools/video-frame-interpolation",
    headers=HEADERS,
    json={"video_url": "https://example.com/source.mp4", "fps": 60},
)
submit.raise_for_status()
task_id = submit.json()["task_id"]
print("task_id:", task_id)

# 2. 轮询任务状态（建议每 5–15 秒一次）
while True:
    time.sleep(10)
    task = requests.get(f"{BASE}/api/v1/tasks/{task_id}", headers=HEADERS).json()
    print(task["status"])
    if task["status"] in ("completed", "failed"):
        break

if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

# 3. 下载成片（临时链接约 2 小时失效，下载无需 Authorization）
video_url = task["result"]["video_url"]
data = requests.get(video_url).content       # 注意：不要带 HEADERS
with open("result.mp4", "wb") as f:
    f.write(data)
print("已保存 result.mp4，时长（秒）：", task["result"]["duration"])
```

<Warning>
成片 `video_url` 为**临时链接**，约 **2 小时**后失效，请尽快下载并转存到你自己的存储。
</Warning>

---

URL: https://docs.looprouter.com/video-processing/vod/overview.md

# VOD 接入说明

> 火山云 VOD 系列能力的 AK/SK 鉴权、Base URL、统一响应结构与错误码。官方 SDK 换域名与密钥即可接入。

VOD 系列接口格式与火山云视频点播（VOD）OpenAPI 完全一致——若你已有基于火山官方 VOD SDK 的接入代码，只需**替换接入域名与 AK/SK** 即可直接使用，无需改动任何签名逻辑。

## 基础信息

- **Base URL**：

  ```
  https://api.looprouter.com/api/vod
  ```

- **鉴权**：使用 **AK/SK**（Access Key / Secret Key），签名方式与火山官方一致。AK/SK 在 [控制台](https://console.looprouter.com) 获取——系统已为你生成好，直接填入官方 SDK 即可。SDK 的 `region` 保持官方默认 `cn-north-1`。

- **请求分派**：与官方一致，所有请求打到同一入口，按 query 参数 `Action` 与 `Version` 区分接口。

<Warning>
请务必使用 `api.looprouter.com` 域名接入（而非 `looprouter.com` 主站域名），否则请求无法到达 API 服务。
</Warning>

## 支持的 Action

| Action | HTTP 方法 | Version | 用途 |
| --- | --- | --- | --- |
| `UploadMediaByUrl` | POST | `2020-08-01` | 提交源视频链接，获取上传作业 ID |
| `QueryUploadTaskInfo` | GET | `2020-08-01` | 查询上传结果，换取媒资 `Vid` |
| `AsyncVCreativeTask` | POST | `2018-01-01` | 提交漫剧转绘任务 |
| `GetVCreativeTaskResult` | GET | `2018-01-01` | 轮询转绘任务结果 |
| `GetPlayInfo` | GET | `2020-08-01` | 获取成片播放地址 |

完整链路与各 Action 的参数详解见 [AI 漫剧转绘](/video-processing/vod/comic-style-transfer)。

## 统一响应结构

### 成功

```json
{
  "ResponseMetadata": {
    "RequestId": "b1e6c2f0-…",
    "Action": "AsyncVCreativeTask",
    "Version": "2018-01-01",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": { "…": "各 Action 的结果对象" }
}
```

### 失败

失败时无 `Result`，错误信息挂在 `ResponseMetadata.Error`：

```json
{
  "ResponseMetadata": {
    "RequestId": "b1e6c2f0-…",
    "Action": "AsyncVCreativeTask",
    "Version": "2018-01-01",
    "Service": "vod",
    "Region": "cn-north-1",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "ParamObj.input must be in the form vid://<Vid>"
    }
  }
}
```

### 错误码

| HTTP | `Error.Code` | 说明 |
| --- | --- | --- |
| 400 | `InvalidParameter` | 请求参数非法，`Message` 会说明具体原因 |
| 400 | `InvalidAction` | 不支持的 `Action` |
| 401 | `InvalidCredential` | AK/SK 无效或签名错误 |
| 403 | `QuotaExceeded` | 账户余额不足或超出可用额度 |
| 404 | `ResourceNotFound` | 任务 / 媒资不存在，或成片尚未就绪 |
| 429 | `Throttling` | 请求过于频繁或未完成任务数超上限 |
| 503 | `ServiceUnavailable` | 服务暂不可用 |
| 其它 5xx | `InternalError` | 内部错误，请稍后重试 |

## 成片链接有效期

<Warning>
`GetPlayInfo` 返回的播放地址为**临时链接**，约 **2 小时**后失效。请在任务成功后**尽快下载**并转存到你自己的存储。下载时无需携带鉴权信息。
</Warning>

## 计费

按**实际用量后付费**：转绘任务成功后按**实际输出时长与分辨率档位**计费；任务失败**不收费**。详见 [视频处理总览](/video-processing/overview#计费与结算)。

## 下一步

<CardGroup cols={2}>
  <Card title="AI 漫剧转绘" icon="palette" href="/video-processing/vod/comic-style-transfer">
    完整 5 步链路：上传 → 提交 → 轮询 → 取片
  </Card>
  <Card title="常见问题" icon="circle-question" href="/video-processing/faq">
    签名排错、计费时机、失败退费
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/video-processing/vod/comic-style-transfer.md

# AI 漫剧转绘

> 把真人 / 实拍视频整体转绘为漫画风格成片。5 步链路：上传 → 查上传 → 提交转绘 → 轮询结果 → 取播放地址。兼容火山云 VOD 官方格式。

AI 漫剧转绘把真人 / 实拍视频整体转绘为**漫画风格**成片，保留原片运动与构图，适合短剧漫改、二创内容、动漫营销素材等场景。支持 `480p` / `720p` / `1080p` 输出与自定义转绘风格。

调用链路与火山官方 VOD 完全一致，共 5 步：

<Steps>
  <Step title="提交源视频（UploadMediaByUrl）">
    提交源视频公网链接，返回上传作业 `JobId`。
  </Step>
  <Step title="查询上传（QueryUploadTaskInfo）">
    用 `JobId` 查询，返回媒资 `Vid`。
  </Step>
  <Step title="提交转绘任务（AsyncVCreativeTask）">
    用 `vid://<Vid>` 提交转绘，返回任务 ID `VCreativeId`。
  </Step>
  <Step title="轮询任务结果（GetVCreativeTaskResult）">
    轮询直至 `Status` 为 `success`，从 `OutputJson` 拿到成片 `Vid`。
  </Step>
  <Step title="获取播放地址（GetPlayInfo）">
    用成片 `Vid` 换取播放地址，尽快下载（临时链接约 2 小时失效）。
  </Step>
</Steps>

鉴权与统一响应结构见 [VOD 接入说明](/video-processing/vod/overview)。以下 `Result` 均指成功响应中的 `Result` 对象。

---

## 步骤 1 · 提交源视频

```
POST /api/vod?Action=UploadMediaByUrl&Version=2020-08-01
```

### 请求体

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `SpaceName` | string | 否 | 空间名（兼容保留，可不传） |
| `URLSets` | array | 是 | 上传项数组，当前每次处理第一条 |
| `URLSets[].SourceUrl` | string | 是 | 源视频公网链接（`http(s)`，最长 1024 字符） |
| `URLSets[].FileExtension` | string | 否 | 文件扩展名（兼容保留） |
| `URLSets[].CallbackArgs` | string | 否 | 回调透传参数（兼容保留） |

```json
{
  "URLSets": [
    { "SourceUrl": "https://example.com/comic-source.mp4" }
  ]
}
```

### 响应 `Result`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `Data` | array | 上传作业数组 |
| `Data[].JobId` | string | 上传作业 ID（用于步骤 2） |
| `Data[].SourceUrl` | string | 回显源链接 |

```json
{
  "Result": {
    "Data": [
      { "JobId": "lrv1_xxxx.yyyy", "SourceUrl": "https://example.com/comic-source.mp4" }
    ]
  }
}
```

---

## 步骤 2 · 查询上传

```
GET /api/vod?Action=QueryUploadTaskInfo&Version=2020-08-01&JobIds={JobId}
```

### Query 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `JobIds` | 是 | 步骤 1 返回的上传作业 ID（支持逗号分隔，当前每次处理第一个） |

### 响应 `Result`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `MediaInfoList` | array | 媒资信息列表 |
| `MediaInfoList[].JobId` | string | 回显作业 ID |
| `MediaInfoList[].SourceUrl` | string | 回显源链接 |
| `MediaInfoList[].State` | string | 上传状态，`Success` 表示可用 |
| `MediaInfoList[].Vid` | string | 媒资 `Vid`（用于步骤 3） |
| `NotExistJobIds` | array | 未识别的作业 ID |

```json
{
  "Result": {
    "MediaInfoList": [
      {
        "JobId": "lrv1_xxxx.yyyy",
        "SourceUrl": "https://example.com/comic-source.mp4",
        "State": "Success",
        "Vid": "lrv1_aaaa.bbbb"
      }
    ],
    "NotExistJobIds": []
  }
}
```

---

## 步骤 3 · 提交转绘任务

```
POST /api/vod?Action=AsyncVCreativeTask&Version=2018-01-01
```

<Note>
计费按**实际用量后付费**：任务成功后按实际输出时长与分辨率档位计费；任务失败**不收费**。
</Note>

### 请求体

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `Uploader` | string | 否 | 上传者标识（兼容保留） |
| `Scene` | string | 否 | 场景标识，漫剧转绘为 `videostyletrans`（兼容保留，可不传） |
| `CallbackArgs` | string | 否 | 回调透传参数（兼容保留） |
| `ParamObj` | object | 是 | 转绘参数 |
| `ParamObj.input` | string | 是 | 输入媒资，必须形如 `vid://<Vid>`（步骤 2 返回的 Vid） |
| `ParamObj.resolution` | string | 是 | 输出分辨率档位：`480p` / `720p` / `1080p` |
| `ParamObj.style` | string | 否 | 转绘风格描述（最长 100 字符；留空使用默认风格） |

```json
{
  "Scene": "videostyletrans",
  "ParamObj": {
    "input": "vid://lrv1_aaaa.bbbb",
    "resolution": "1080p",
    "style": "manga"
  }
}
```

### 响应 `Result`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `VCreativeId` | string | 转绘任务 ID（用于步骤 4） |
| `Code` | int | 固定 `0` |
| `BaseResp.StatusCode` | int | 固定 `0` |
| `BaseResp.StatusMessage` | string | 固定 `success` |

```json
{
  "Result": {
    "VCreativeId": "vg_7a6d4f30",
    "Code": 0,
    "BaseResp": { "StatusCode": 0, "StatusMessage": "success" }
  }
}
```

---

## 步骤 4 · 轮询任务结果

```
GET /api/vod?Action=GetVCreativeTaskResult&Version=2018-01-01&VCreativeId={VCreativeId}
```

建议每 10–30 秒轮询一次（转绘耗时随视频时长与分辨率变化，通常为分钟级）。

### Query 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `VCreativeId` | 是 | 步骤 3 返回的任务 ID |

### 响应 `Result`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `Scene` | string | 固定 `videostyletrans` |
| `VCreativeId` | string | 回显任务 ID |
| `ParamObj` | string | **JSON 字符串**，回显提交参数 |
| `Status` | string | 任务状态：`start`（进行中）/ `success`（成功）/ `failed_run`（失败） |
| `OutputJson` | string | **JSON 字符串**。成功时为 `{"vid":"<成片 Vid>"}`；进行中 / 失败为空串 |

```json
{
  "Result": {
    "Scene": "videostyletrans",
    "VCreativeId": "vg_7a6d4f30",
    "ParamObj": "{\"input\":\"vid://lrv1_aaaa.bbbb\",\"resolution\":\"1080p\",\"style\":\"manga\"}",
    "Status": "success",
    "OutputJson": "{\"vid\":\"lrv1_cccc.dddd\"}"
  }
}
```

<Note>
`ParamObj` 与 `OutputJson` 是**序列化后的 JSON 字符串**（与官方一致），需要再做一次 JSON 解析。任务失败（`failed_run`）**不收费**。
</Note>

---

## 步骤 5 · 获取播放地址

```
GET /api/vod?Action=GetPlayInfo&Version=2020-08-01&Vid={成片Vid}
```

### Query 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `Vid` | 是 | 步骤 4 `OutputJson` 中的成片 `Vid` |

### 响应 `Result`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `Vid` | string | 回显成片 Vid |
| `Status` | int | `10` 表示已就绪可播 |
| `FileType` | string | 固定 `video` |
| `TotalCount` | int | 播放信息条数 |
| `Duration` | number | 成片时长（秒） |
| `PlayInfoList` | array | 播放信息列表 |

**`PlayInfoList[]` 元素**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `MainPlayUrl` | string | 成片播放 / 下载地址（**临时链接，约 2 小时后失效**） |
| `FileType` | string | 固定 `video` |
| `Format` | string | 封装格式，如 `mp4` |
| `Width` | int | 成片宽（像素） |
| `Height` | int | 成片高（像素） |
| `Codec` | string | 视频编码，如 `H264`（可选，视素材而定） |
| `Bitrate` | int | 码率（bps）（可选） |
| `Size` | number | 文件大小（字节）（可选） |
| `Md5` | string | 文件 MD5（可选） |
| `Definition` | string | 清晰度档位，如 `1080p`（可选） |
| `Quality` | string | 画质标记，如 `normal`（可选） |

```json
{
  "Result": {
    "Vid": "lrv1_cccc.dddd",
    "Status": 10,
    "FileType": "video",
    "TotalCount": 1,
    "Duration": 12.5,
    "PlayInfoList": [
      {
        "MainPlayUrl": "https://…/out.mp4?…",
        "FileType": "video",
        "Format": "mp4",
        "Width": 1920,
        "Height": 1080,
        "Codec": "H264",
        "Bitrate": 2500000,
        "Size": 9437184,
        "Md5": "d41d8cd98f00b204e9800998ecf8427e",
        "Definition": "1080p",
        "Quality": "normal"
      }
    ]
  }
}
```

<Warning>
- `MainPlayUrl` 为**临时链接**，约 **2 小时**后失效，请尽快下载并转存到你自己的存储。
- 任务未成功或成片尚未就绪时，返回 HTTP 404 + `Error.Code = ResourceNotFound`，稍后重试即可。
</Warning>

---

## 端到端调用示例

使用火山官方 VOD SDK（把接入域名指向 `api.looprouter.com`、填入控制台获取的 AK/SK）依次调用：

```text 调用顺序
# 1) 提交源视频 → JobId
POST /api/vod?Action=UploadMediaByUrl&Version=2020-08-01
     body: { "URLSets": [ { "SourceUrl": "https://…/src.mp4" } ] }
  -> Result.Data[0].JobId

# 2) 查询上传 → Vid
GET  /api/vod?Action=QueryUploadTaskInfo&Version=2020-08-01&JobIds=<JobId>
  -> Result.MediaInfoList[0].Vid

# 3) 提交转绘 → VCreativeId（开始计费）
POST /api/vod?Action=AsyncVCreativeTask&Version=2018-01-01
     body: { "ParamObj": { "input": "vid://<Vid>", "resolution": "1080p", "style": "manga" } }
  -> Result.VCreativeId

# 4) 轮询直到 Status=success → 成片 Vid
GET  /api/vod?Action=GetVCreativeTaskResult&Version=2018-01-01&VCreativeId=<VCreativeId>
  -> JSON.parse(Result.OutputJson).vid

# 5) 获取播放地址（尽快下载，约 2 小时失效）
GET  /api/vod?Action=GetPlayInfo&Version=2020-08-01&Vid=<成片Vid>
  -> Result.PlayInfoList[0].MainPlayUrl
```

---

URL: https://docs.looprouter.com/video-processing/faq.md

# 常见问题

> 视频处理接口的常见问题：接入与迁移、视频来源、成片有效期、计费、参数排错。

## 接入与迁移

<AccordionGroup>
  <Accordion title="我已经在用火山云官方 API，迁移过来要改什么？">
    只需要改**两样**：

    - **域名**：AI MediaKit 系列把 Base URL 换成 `https://api.looprouter.com/api/aimediakit`；VOD 系列换成 `https://api.looprouter.com/api/vod`。
    - **密钥**：AI MediaKit 用控制台创建的 `sk-` API Key；VOD 用控制台获取的 AK/SK。

    请求路径、参数、响应结构与官方一致，已有代码与官方 SDK 无需改动签名 / 解析逻辑。
  </Accordion>
  <Accordion title="AI MediaKit 和 VOD 两个系列的鉴权有什么区别？">
    - **AI MediaKit**（插帧 / 字幕擦除 / 画质增强）：请求头携带 `Authorization: Bearer sk-你的APIKey`，在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建。
    - **VOD**（漫剧转绘）：使用 AK/SK 签名（与火山官方签名方式一致），AK/SK 在控制台获取，直接填入官方 SDK 即可。
  </Accordion>
  <Accordion title="VOD 请求返回 401 InvalidCredential，怎么排查？">
    依次检查：

    1. 接入域名是否为 `api.looprouter.com`（不是 `looprouter.com` 主站域名）；
    2. AK/SK 是否为控制台获取的当前有效凭据，有没有多余空格；
    3. SDK 的 `region` 是否保持官方默认 `cn-north-1`。
  </Accordion>
</AccordionGroup>

## 视频来源与成片

<AccordionGroup>
  <Accordion title="视频来源有什么要求？">
    提供一个**公网可直接访问**的 `http(s)` 视频链接（最长 1024 字符），不支持 base64 内联数据。带鉴权、防盗链或仅内网可访问的链接会导致任务失败。
  </Accordion>
  <Accordion title="成片链接能用多久？">
    约 **2 小时**。所有能力返回的成片链接（MediaKit 的 `result.video_url`、VOD `GetPlayInfo` 的 `MainPlayUrl`）均为临时链接，请在任务成功后尽快下载并转存到你自己的存储。下载时无需携带鉴权信息。
  </Accordion>
  <Accordion title="成片链接过期了还能重新获取吗？">
    链接失效前可重新调用查询接口获取；但成片文件本身也会在生成约 2 小时后清理，届时即使拿到链接也无法下载。请务必在任务成功后**尽快下载**。
  </Accordion>
</AccordionGroup>

## 计费

<AccordionGroup>
  <Accordion title="费用什么时候扣？">
    按**实际用量后付费**（与火山官方一致）：提交任务时不预扣、不冻结额度；任务**成功后**按**实际输出时长 × 输出分辨率档位**计费，从账户余额中扣除。
  </Accordion>
  <Accordion title="任务失败会扣费吗？">
    不会。任务失败时（包括源视频下载失败、参数在处理阶段校验不通过等）**不产生任何费用**。
  </Accordion>
  <Accordion title="提交时报 403 QuotaExceeded？">
    账户余额不足或超出可用额度。请在 [控制台](https://console.looprouter.com) 充值后重试。
  </Accordion>
</AccordionGroup>

## 任务与轮询

<AccordionGroup>
  <Accordion title="要多久才能拿到结果？">
    处理为异步任务，耗时随视频时长、分辨率与所选能力变化，通常为分钟级。建议 MediaKit 任务每 5–15 秒轮询一次，漫剧转绘每 10–30 秒轮询一次。
  </Accordion>
  <Accordion title="可以同时提交很多任务吗？">
    单个账户的**未完成任务数**有上限，超过会返回 429。请等待已有任务完成后再提交新任务。
  </Accordion>
  <Accordion title="GetPlayInfo 返回 404 ResourceNotFound？">
    成片尚未就绪。请先确认 `GetVCreativeTaskResult` 的 `Status` 已是 `success`，再用 `OutputJson` 中的成片 `Vid` 调用 `GetPlayInfo`；若刚成功，稍等片刻重试即可。
  </Accordion>
</AccordionGroup>

## 参数排错

<AccordionGroup>
  <Accordion title="智能插帧提示 fps 非法？">
    `fps` 需满足三个条件：取值在 `[15, 120]` 区间；**大于源视频帧率**；**不超过源帧率的 4 倍**。例如源视频 24 fps，合法目标为 24–96 fps。前一条在提交时校验，后两条在处理阶段校验（不满足时任务失败并全额退款）。
  </Accordion>
  <Accordion title="画质增强提示 scene / bit_depth 不支持？">
    这两个参数有版本限制：`scene` 仅**标准版**（`tool_version=standard`）接受；`bit_depth` 仅**专业版**（`tool_version=professional`）接受。大模型版两者都不支持。
  </Accordion>
  <Accordion title="同时传了 bitrate 和 bitrate_level 报错？">
    两者**至多提供其一**：`bitrate` 指定具体码率（kbps），`bitrate_level` 指定档位（`low`/`medium`/`high`）。同时提供会返回参数错误。
  </Accordion>
  <Accordion title="传了 resolution_limit 报错？">
    当前请改用 `resolution` 指定输出分辨率档位（如 `720p` / `1080p` / `2k`）。
  </Accordion>
  <Accordion title="漫剧转绘提示 ParamObj.input 非法？">
    `ParamObj.input` 必须形如 `vid://<Vid>`，其中 `Vid` 是**步骤 2 `QueryUploadTaskInfo` 返回的媒资 Vid**（不要漏掉 `vid://` 前缀，也不要填 JobId 或任务 ID）。
  </Accordion>
  <Accordion title="漫剧转绘 resolution 支持哪些取值？">
    `480p` / `720p` / `1080p` 三档。`style` 为可选的风格描述（最长 100 字符），留空使用默认风格。
  </Accordion>
</AccordionGroup>

还有其他问题？联系商务或在 [控制台](https://console.looprouter.com) 提交工单。

---

URL: https://docs.looprouter.com/scenarios/overview.md

# 使用场景总览

> LoopRouter Seedance 视频生成的典型落地场景：电商营销、角色 IP 短剧、真人口播数字人、从火山方舟迁移

LoopRouter 以与火山引擎方舟**完全兼容**的接口提供 Doubao Seedance 2.0 视频生成能力。无论你是做电商短视频、连续剧情短剧，还是真人口播、数字人，都可以用同一套 API Key、同一套异步任务接口跑通。本页汇总最常见的落地场景，并指向对应的实操文档。

## 四类核心场景

<CardGroup cols={2}>
  <Card title="电商与营销短视频" icon="cart-shopping" href="/scenarios/ecommerce-marketing">
    商品展示、广告 Bumper、节日营销素材批量生产，文生视频 + 图生视频
  </Card>
  <Card title="角色 IP 与短剧一致性" icon="masks-theater" href="/scenarios/character-ip">
    用多模态参考 + 素材库锁定角色形象，跨镜头保持同一主角
  </Card>
  <Card title="真人口播与数字人" icon="user-check" href="/scenarios/digital-human">
    真人认证后生成本人口播视频，全流程 API 化，无需人工审核
  </Card>
  <Card title="从火山方舟迁移" icon="arrows-turn-right" href="/scenarios/migrate-from-ark">
    只改 Base URL 与 API Key，原有方舟代码零成本迁移
  </Card>
</CardGroup>

## 能力与场景对照

| 你想做的 | 用到的能力 | 参考文档 |
| --- | --- | --- |
| 一句话生成一段视频 | 文生视频 | [快速开始](/getting-started) |
| 用一张商品图动起来 | 首帧图生视频 | [视频生成 API](/api-capabilities/seedance2/video-generation) |
| 指定开头与结尾画面 | 首尾帧图生视频 | [视频生成 API](/api-capabilities/seedance2/video-generation) |
| 让多个镜头是同一个角色 | 多模态参考 + 素材库 | [素材引用实战](/asset-management/asset-reference) |
| 用真人形象出镜口播 | 真人认证 + 素材库 | [真人认证接口](/asset-management/real-person) |
| 生成带同步配音的视频 | `generate_audio`（默认开启） | [能力总览](/api-capabilities/seedance2/overview) |
| 串联长视频 | 末帧续接 / 草稿续画 | [视频生成 API](/api-capabilities/seedance2/video-generation) |

## 接入四步

<Steps>
  <Step title="选定场景">
    先明确产出形态（横屏/竖屏、时长、是否需要真人/固定角色），对照上表选择能力。
  </Step>
  <Step title="获取 API Key">
    在 [控制台 → 令牌](https://console.looprouter.com/keys) 创建 `sk-` 开头的 API Key，视频与素材库共用同一把 Key。
  </Step>
  <Step title="按文档接入">
    参照对应场景文档编写创建任务 → 轮询 → 下载的最短链路；也可以在 [AI 集成指南](/ai-usage) 一键把文档交给 AI 帮你写代码。
  </Step>
  <Step title="批量与优化">
    跑通单条后再上量。注意异步任务、限流重试与计费规则，见下方最佳实践。
  </Step>
</Steps>

## 最佳实践

<CardGroup cols={3}>
  <Card title="先小后大" icon="gauge-simple">
    先用 `720p` / 5 秒验证提示词与构图，满意后再提高分辨率与时长，控制试错成本。
  </Card>
  <Card title="异步不阻塞" icon="clock">
    创建任务只返回 ID，用轮询（15–30 秒/次）或任务列表批量获取结果，不要同步等待。
  </Card>
  <Card title="及时转存" icon="download">
    成片 `video_url` 约 2 小时过期，生成后尽快转存到自己的对象存储。
  </Card>
</CardGroup>

<Note>
LoopRouter 当前聚焦 Doubao Seedance 视频生成。如果你有文本 / 图像 / 多模型聚合等需求，可通过 [控制台](https://console.looprouter.com) 内工单与我们沟通。
</Note>

---

URL: https://docs.looprouter.com/scenarios/ecommerce-marketing.md

# 电商与营销短视频

> 用 Seedance 2.0 批量生产商品展示、广告 Bumper 与节日营销短视频：文生视频 + 首帧图生视频

电商与营销是视频生成最直接的落地场景：把一句卖点或一张商品图，快速变成可投放的短视频。本页给出选型建议与可直接套用的请求示例。

## 适合的产出

<CardGroup cols={2}>
  <Card title="商品展示视频" icon="box-open">
    上传一张商品主图，用首帧图生视频让它旋转、展开、场景化
  </Card>
  <Card title="广告 Bumper / 片头" icon="film">
    文生视频生成 5–6 秒品牌氛围片段，配合 `generate_audio` 同步音效
  </Card>
  <Card title="节日 / 促销素材" icon="gift">
    同一提示词模板批量替换主题词，快速铺量多套营销物料
  </Card>
  <Card title="竖屏投流素材" icon="mobile">
    用 `ratio: 9:16` 直接产出适配抖音 / 视频号的竖屏视频
  </Card>
</CardGroup>

## 方案一：一张商品图动起来（首帧图生视频）

把商品图作为首帧，让模型基于它生成一段有镜头运动的展示视频。

```bash
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "镜头缓缓环绕这瓶香水，背景是清晨的花园，柔和逆光，高级质感"},
      {"type": "image_url", "image_url": {"url": "https://example.com/perfume.jpg"}}
    ],
    "resolution": "1080p",
    "ratio": "9:16",
    "duration": 5
  }'
```

<Tip>
商品图不含真人时可直接用公网 URL 作参考图。若画面里有真实人脸模特，请先走 [真人认证](/asset-management/real-person)，否则会被内容审核 403 拒绝。
</Tip>

## 方案二：纯文字生成氛围片（文生视频）

没有素材图时，用一句提示词直接生成品牌氛围片段。

```bash
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "夏日海滩，冰镇饮料的水珠特写，阳光穿过玻璃杯，清爽通透，广告质感"}
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 6
  }'
```

## 批量铺量的推荐做法

<Steps>
  <Step title="模板化提示词">
    固定运镜 / 风格描述，只替换主体词（商品名、场景、卖点），保证多条素材风格统一。
  </Step>
  <Step title="并发提交、集中轮询">
    循环创建多个任务收集 `id`，再用 [任务列表](/api-capabilities/seedance2/video-generation#任务列表与取消) `GET /api/v3/contents/generations/tasks` 分页批量查询状态，避免逐条阻塞。
  </Step>
  <Step title="先低分辨率打样">
    用 `720p` 快速筛掉不满意的提示词，命中后再对少量精品用 `1080p` / `4k` 重出。
  </Step>
  <Step title="及时转存与归档">
    成片链接约 2 小时过期，跑批脚本里下载后立即上传到自己的存储并记录 `task_id`。
  </Step>
</Steps>

<Warning>
促销活动前的批量生产建议错峰进行。高并发时平台会按渠道 RPM 智能排队，遇到 429（`当前分组上游负载已饱和`）请指数退避重试（2s → 4s → 8s），详见 [并发、限流与重试](/faq/concurrency-and-ratelimit)。
</Warning>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    全部参数与生成模式
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    预扣结算与不扣费场景
  </Card>
  <Card title="并发与限流" icon="gauge-high" href="/faq/concurrency-and-ratelimit">
    批量生产的限流应对
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/scenarios/character-ip.md

# 角色 IP 与短剧一致性

> 用多模态参考 + 素材库锁定角色形象，让连续短剧 / IP 系列的多个镜头保持同一主角

做连续剧情短剧或 IP 系列时，最大的痛点是**跨镜头的角色一致性**：每次生成都是一张新面孔就没法讲故事。Seedance 2.0 用「素材库 + 多模态参考」解决这个问题——把角色形象注册成素材，之后每个镜头都以 `asset://` 引用同一素材。

## 核心思路

<Steps>
  <Step title="把角色注册成素材">
    创建 `AIGC` 素材组，上传角色形象图，拿到长期有效的 `asset-` 素材 ID。
  </Step>
  <Step title="每个镜头都引用同一素材">
    生成每个分镜时，在 `content` 里带上 `{"type":"image_url","image_url":{"url":"asset://素材ID"},"role":"reference_image"}`，用不同提示词描述动作与场景。
  </Step>
  <Step title="用末帧续接串成长视频">
    需要连贯长镜头时，用 `return_last_frame` 拿到末帧，作为下一段视频的首帧。
  </Step>
</Steps>

<Note>
动漫 / 风格化角色可以直接用公网 URL 作参考图，无需素材库；但**真实人脸**必须先走 [真人认证](/asset-management/real-person)。素材库完整说明见 [素材库 API](/asset-management/asset-library)。
</Note>

## 分镜示例

同一角色，两个不同镜头，引用同一个 `asset://` 素材：

```json 镜头一
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "图片1中的少女站在樱花树下抬头微笑，花瓣飘落，镜头缓慢上摇"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5
}
```

```json 镜头二
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "图片1中的少女撑伞走过雨中的石板巷，回头看向镜头，画面电影感"},
    {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5
}
```

<Warning>
提示词里用「图片1」「图片2」按 `content` 顺序指代角色，**不要**把 `asset-` 开头的素材 ID 写进提示词文本，否则模型会把它当普通文字。
</Warning>

## 提升一致性的技巧

<CardGroup cols={2}>
  <Card title="一角多图" icon="images">
    同一角色上传「正面全身照 + 自然表情面部特写」两张素材并同时引用，提示词写「图片1为角色全身，图片2为角色面部」
  </Card>
  <Card title="固定 seed" icon="dice">
    对同一分镜微调提示词时固定 `seed`，整体构图更稳定（注意相同 seed 也只是高度相近，非完全一致）
  </Card>
  <Card title="末帧续接" icon="link">
    `return_last_frame: true` 拿到末帧图，作为下一段的首帧，衔接更自然
  </Card>
  <Card title="统一风格描述" icon="palette">
    在每条提示词里保留同一句风格锚点（如「电影感、暖色调、35mm」），跨镜头观感统一
  </Card>
</CardGroup>

## 完整链路

素材注册到生成的端到端代码（含轮询素材 `Active`、轮询任务 `succeeded`、下载成片）见 [素材引用生视频实战](/asset-management/asset-reference)。

<CardGroup cols={3}>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    端到端代码示例
  </Card>
  <Card title="素材库 API" icon="images" href="/asset-management/asset-library">
    素材组与素材管理
  </Card>
  <Card title="真人口播与数字人" icon="user-check" href="/scenarios/digital-human">
    用真人形象出镜
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/scenarios/digital-human.md

# 真人口播与数字人

> 真人认证后用本人形象生成口播视频：活体认证 → 上传真人素材 → 台词驱动的口播生成

想让**真实人物**出镜口播（主播切片、数字人带货、企业宣讲），需要先证明「这是本人授权」。Seedance 2.0 用活体认证把这一步全 API 化：本人刷脸通过后，才能上传其照片并用于生成，从机制上防止深度伪造。

<Info>
未经认证的真实人脸图片直接放进生成请求会被内容审核 **403 拒绝**。这是防深伪的硬性要求，不是可绕过的限制。
</Info>

## 全流程

<Steps>
  <Step title="发起活体认证">
    调用 `CreateVisualValidateSession` 拿到 `BytedToken` 和 `H5Link`。
  </Step>
  <Step title="本人手机刷脸">
    把 `H5Link`（或其二维码）发给本人，用手机浏览器打开完成活体检测，会话约 15 分钟有效。
  </Step>
  <Step title="查询认证结果">
    轮询 `GetVisualValidateResult`，通过后拿到 `LivenessFace` 真人素材组 ID（轮询中返回 404 属正常，表示还没刷完）。
  </Step>
  <Step title="上传真人照片">
    向该素材组 `CreateAsset` 上传本人清晰照片，轮询到 `Active`。
  </Step>
  <Step title="台词驱动口播生成">
    生成请求中以 `asset://` 引用真人素材，台词放进提示词的双引号里。
  </Step>
</Steps>

完整分步接口、响应字段与错误码见 [真人认证接口](/asset-management/real-person)。

## 口播生成示例

台词用双引号包裹，可获得更好的对口型与配音效果：

```bash
curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图片1中的人坐在办公桌前，面向镜头自信地介绍：\"大家好，今天带来一款全新的智能音箱\""},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
    ],
    "resolution": "1080p",
    "ratio": "9:16",
    "duration": 8
  }'
```

<Tip>
`generate_audio` 默认开启，会为台词生成同步人声。若你要用自己的配音后期合成，可设 `generate_audio: false`，只取画面。
</Tip>

## 效果与合规建议

<CardGroup cols={2}>
  <Card title="素材选取" icon="camera">
    同一真人上传「正面全身照 + 自然表情面部特写」两张并同时引用，口播时的面部还原更稳
  </Card>
  <Card title="台词长度" icon="quote-left">
    单条时长 4–15 秒，台词控制在与时长匹配的长度，过长会被截断或语速失真
  </Card>
  <Card title="一人一组" icon="users">
    每次认证对应一个真人素材组；多位出镜人各自认证、各自维护素材组
  </Card>
  <Card title="授权留痕" icon="file-signature">
    仅对已获得肖像授权的本人发起认证；`BytedToken` 与素材 ID 属敏感凭据，请妥善保管
  </Card>
</CardGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    认证全流程 API
  </Card>
  <Card title="真人认证与内容安全" icon="shield-halved" href="/faq/real-person-and-safety">
    审核规则常见问题
  </Card>
  <Card title="角色 IP 与短剧" icon="masks-theater" href="/scenarios/character-ip">
    虚拟角色一致性
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/scenarios/migrate-from-ark.md

# 从火山引擎方舟迁移

> 已有火山引擎方舟（Ark）Seedance 代码？只改 Base URL 与 API Key 即可迁移到 LoopRouter

LoopRouter 的 Seedance 2.0 接口与火山引擎方舟（Ark）**同路径、同参数、同响应结构**。如果你已经在用方舟的官方 SDK 或自写代码，迁移基本上只有两处改动：**Base URL** 和 **API Key**。

## 只改两处

<CardGroup cols={2}>
  <Card title="Base URL" icon="link">
    把方舟域名换成 `https://api.looprouter.com`，路径 `/api/v3/contents/generations/tasks` 保持不变（`/api` 前缀不能省略）
  </Card>
  <Card title="API Key" icon="key">
    把方舟的 Key 换成 LoopRouter 的 `sk-` 令牌，请求头仍是 `Authorization: Bearer <key>`
  </Card>
</CardGroup>

## 迁移前后对照

```diff
- BASE = "https://ark.cn-beijing.volces.com"
+ BASE = "https://api.looprouter.com"

- headers = {"Authorization": "Bearer <方舟 API Key>"}
+ headers = {"Authorization": "Bearer sk-你的LoopRouterKey"}

  # 其余请求体、轮询逻辑、响应解析都不用改
  POST {BASE}/api/v3/contents/generations/tasks
  GET  {BASE}/api/v3/contents/generations/tasks/{task_id}
```

模型名直接用 `doubao-seedance-2-0-260128`（与方舟快照版本号一致），**不需要**方舟那种 `ep-` 开头的接入点 ID。

## 需要留意的差异点

<Warning>
接入前对照以下几点，可避开绝大多数排障时间：

1. **分辨率白名单**：可用档位由[分组](/user-groups)决定——VIP 组支持 `480p`、`720p`、`1080p`、`4k` 全档位，补贴组支持 `720p`、`1080p`。传分组外的值会返回 400 且不扣费。
2. **不支持回调**：`callback_url` 会被 400 拒绝，请用轮询查询任务状态。
3. **成功终态是 `succeeded`**（不是 `completed`）；终态匹配 `succeeded / failed / cancelled / expired`。
4. **真人脸不能直传**：真实人脸图片需先走 [真人认证](/asset-management/real-person)，再以 `asset://` 引用。
5. **Python `requests`** 建议加请求头 `Accept-Encoding: identity`，避免个别网络环境 gzip 解码异常。
6. **成片链接约 2 小时过期**，请及时转存；下载时不要带 `Authorization` 头。
</Warning>

## LoopRouter 额外提供的能力

在与方舟兼容的基础上，LoopRouter 还补充了几个原厂之外的便利接口：

| 能力 | 说明 |
| --- | --- |
| 任务列表 | `GET /api/v3/contents/generations/tasks` 分页 / 按状态筛选批量查询 |
| 取消任务 | `DELETE /api/v3/contents/generations/tasks/{id}` 取消排队中的任务 |
| 统一计费与日志 | 控制台「日志中心」逐条核对预扣与结算，被拒绝的请求不扣费 |
| 渠道级智能调度 | 高并发时按 RPM 排队重试，任务不易直接失败 |

## 迁移自测清单

<Steps>
  <Step title="替换 Base URL 与 Key">
    改完后先跑一条最简单的文生视频（`720p` / 5 秒）验证连通。
  </Step>
  <Step title="核对终态判断">
    确认代码里判断的是 `succeeded`，且覆盖了 `failed / cancelled / expired`。
  </Step>
  <Step title="移除回调依赖">
    如果原来用 `callback_url`，改为轮询查询接口。
  </Step>
  <Step title="校验计费">
    在 [控制台日志中心](https://console.looprouter.com) 核对预扣与结算记录是否符合预期。
  </Step>
</Steps>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    参数与响应详解
  </Card>
  <Card title="API Key 与鉴权" icon="key" href="/faq/api-key-and-auth">
    令牌与请求头
  </Card>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/model-and-async.md

# 模型选择与异步任务

> 该用哪个模型？为什么创建任务只返回 id 没有视频？succeeded 还是 completed？异步任务与轮询的常见疑问

<AccordionGroup>
  <Accordion title="有哪些模型可以用，该怎么选？">
    当前对外提供 `doubao-seedance-2-0-260128`（标准版），支持文生视频、首帧 / 首尾帧图生视频、多模态参考四种模式，输出最高 `4k`（可用分辨率档位依[分组](/user-groups)而定）。直接使用该模型名即可（与火山官方快照版本号一致），不需要 `ep-` 开头的接入点 ID。实际可用模型以 [控制台「模型广场」](https://console.looprouter.com) 为准。
  </Accordion>
  <Accordion title="为什么创建任务只返回一个 id，没有视频？">
    这是**异步任务**接口。创建请求只把任务入队并返回 `{"id": "..."}`，视频需要轮询 `GET /api/v3/contents/generations/tasks/{id}` 直到状态变为 `succeeded`，再从 `content.video_url` 下载成片。720p / 5 秒的典型生成耗时约 2–5 分钟。
  </Accordion>
  <Accordion title="成功状态是 succeeded 还是 completed？">
    是 **`succeeded`**。任务状态机为 `queued → running → succeeded / failed / cancelled / expired`。判断终态时请匹配这四个值，不要用 `completed`。
  </Accordion>
  <Accordion title="轮询间隔多久合适？">
    建议 **15–30 秒**查询一次。过于频繁的轮询没有意义（生成本身需要几分钟），还可能触发限流。批量任务可以用任务列表接口 `GET /api/v3/contents/generations/tasks` 一次性分页查询多个任务的状态。
  </Accordion>
  <Accordion title="支持 callback 回调吗？">
    不支持。传 `callback_url` 会被 **400 拒绝**，请使用轮询获取任务结果。
  </Accordion>
  <Accordion title="任务会保留多久？之前的任务还能查到吗？">
    任务记录长期保留，可随时用查询接口或任务列表回查。但注意成片 `content.video_url` 是约 2 小时有效的临时链接，过期后重新查询任务会拿到新链接——详见 [网络、下载与常见报错](/faq/network-and-download)。
  </Accordion>
  <Accordion title="同一个 seed 能得到完全相同的视频吗？">
    不能保证完全一致。相同 `seed` 与参数会得到高度相近的结果，适合在微调提示词时保持整体构图稳定。
  </Accordion>
  <Accordion title="能生成多长的视频？怎么做长视频？">
    Seedance 2.0 单次 4–15 秒，Seedance 2.5 单次 4–30 秒（均可用 `duration: -1` 由模型决定）。要做更长的连续视频，用 `return_last_frame` 拿到末帧作为下一段首帧，把多段串起来；2.5 首帧任务须使用 `ratio: adaptive`。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览" icon="circle-info" href="/api-capabilities/seedance2/overview">
    模型清单与技术规格
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    参数、状态机与响应
  </Card>
  <Card title="分辨率与时长" icon="expand" href="/faq/resolution-ratio-duration">
    分辨率 / 宽高比常见问题
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/resolution-ratio-duration.md

# 分辨率、宽高比与时长

> 各分组支持哪些分辨率？adaptive 是什么？duration -1 怎么计费？分辨率、宽高比与时长的常见问题

<AccordionGroup>
  <Accordion title="支持哪些分辨率？为什么传 480p / 4k 会报错？">
    可用的分辨率档位由 API Key 所在的[分组](/user-groups)决定：**VIP 组**支持 `480p`、`720p`、`1080p`、`4k` 全档位，**补贴组**支持 `720p`、`1080p` 两档。传入分组不支持的档位会返回 **400**（错误信息会列出当前可用档位），且**不扣费**。
  </Accordion>
  <Accordion title="支持哪些宽高比？adaptive 是什么？">
    `ratio` 支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`。默认是 `adaptive`——跟随输入素材的比例自动决定。竖屏投流用 `9:16`，横屏用 `16:9`。
  </Accordion>
  <Accordion title="时长怎么设置？默认多长？">
    `duration` 为 4–15 的整数秒，默认 **5 秒**。也可以传 `-1` 让模型自行决定时长，此时按实际产出计费。帧率固定 24fps，不可调。
  </Accordion>
  <Accordion title="duration: -1 或 ratio: adaptive 怎么计费？">
    这两种「由模型决定」的参数下，实际费用以任务成功后响应里回填的**真实时长 / 分辨率**为准，与提交时的预扣金额可能有差额，结算时自动多退少补。想要费用完全可预期，就显式指定 `duration` 与 `resolution`。
  </Accordion>
  <Accordion title="分辨率越高越贵吗？4k 值得用吗？">
    是。计费按「时长 × 输出宽 × 输出高 × 帧率」口径折算的视频 token 数结算，分辨率越高、时长越长，token 越多。建议先用 `720p` 打样验证提示词，命中后再对精品用 `1080p` / `4k` 重出，控制试错成本。
  </Accordion>
  <Accordion title="参考图的尺寸有什么要求？">
    图片格式 jpeg/png/webp/bmp/tiff/gif/heic/heif，宽高比需在 (0.4, 2.5) 之间，边长在 (300, 6000) 像素之间，单张小于 30MB。不满足会在校验或素材处理阶段失败。
  </Accordion>
  <Accordion title="首尾帧和参考图能混用吗？">
    不能。同一请求中，首帧 / 首尾帧（`role: first_frame` / `last_frame`）与参考图（`role: reference_image`）三种图片用法互斥，只能选一种。多模态参考模式下最多 9 张参考图 + 3 段参考视频 + 3 段参考音频。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览" icon="circle-info" href="/api-capabilities/seedance2/overview">
    技术规格全表
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    预扣结算规则
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    参数速查
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/concurrency-and-ratelimit.md

# 并发、限流与重试

> 429 是什么意思？并发上限多少？如何指数退避重试？高并发批量生产的限流应对

<AccordionGroup>
  <Accordion title="平台是怎么做限流的？">
    LoopRouter 按**渠道维度做 RPM 智能调度**：并发高峰时任务会短暂排队而不是直接失败。此外对每个账号的模型请求也有速率保护。整体目标是「高并发下任务不丢失」，而不是简单地拒绝。
  </Accordion>
  <Accordion title="收到 429 怎么办？">
    429 表示 `当前分组上游负载已饱和，请稍后再试`。建议**指数退避重试**：2s → 4s → 8s，逐步拉长间隔。不要收到 429 就立刻高频重试，那会让排队更拥堵。
  </Accordion>
  <Accordion title="并发上限是多少？">
    视频生成是异步任务，天然适合高并发提交——你可以循环创建大量任务收集 `id`，再集中轮询。真正的瓶颈在上游渠道的处理速度而非创建接口。如果你的业务需要更高的稳定并发额度，请通过 [控制台](https://console.looprouter.com) 工单联系我们评估。
  </Accordion>
  <Accordion title="批量生产（跑批）的推荐姿势？">
    1）并发提交任务、集中收集 `id`；2）用任务列表接口 `GET /api/v3/contents/generations/tasks` 分页批量查询状态，而不是每个任务单独长轮询；3）对 429 / 5xx 指数退避重试；4）成片及时下载转存。详见 [电商与营销短视频](/scenarios/ecommerce-marketing) 里的跑批实践。
  </Accordion>
  <Accordion title="素材库操作也会限流吗？">
    会，但有自动排队缓冲。短时突发的素材注册请求会先排队等待（最长约 5 秒）而不是立即失败，超出等待窗口才返回 429。素材相关的 503 `NoAvailableAssetChannel` 表示当前账号的素材库服务暂未就绪，需联系我们开通。
  </Accordion>
  <Accordion title="哪些错误该重试，哪些不该？">
    **该重试**：429（限流）、5xx（服务端临时异常）——指数退避。**不该重试**：400（参数错误，重试还是错）、401/403（鉴权 / 权限 / 审核问题，需修正请求）、404（任务或资源不存在）。盲目重试 4xx 只会浪费配额。
  </Accordion>
</AccordionGroup>

## 重试参考实现

```python
import time, requests

def create_with_retry(session, url, headers, body, max_retries=5):
    delay = 2
    for attempt in range(max_retries):
        resp = session.post(url, headers=headers, json=body)
        if resp.status_code < 400:
            return resp.json()
        # 仅对 429 / 5xx 退避重试；4xx 直接抛出
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(delay)
            delay *= 2
            continue
        resp.raise_for_status()
    raise RuntimeError("重试多次仍失败，请稍后再试")
```

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    错误响应与状态码
  </Card>
  <Card title="电商与营销" icon="cart-shopping" href="/scenarios/ecommerce-marketing">
    批量生产实践
  </Card>
  <Card title="服务状态" icon="wave-pulse" href="/live/overview">
    上游负载与维护动态
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/api-key-and-auth.md

# API Key 与鉴权

> sk- 令牌怎么创建？请求头怎么写？401 / 403 怎么排查？/api 前缀能省略吗？

<AccordionGroup>
  <Accordion title="API Key 在哪里创建？">
    在 [控制台 → 令牌](https://console.looprouter.com/keys) 新建一个令牌，得到形如 `sk-xxxx` 的 API Key。视频生成与素材库 / 真人认证**共用同一把 Key**，无需单独申请。请妥善保管，不要提交到代码仓库或泄露给不信任的一方。
  </Accordion>
  <Accordion title="请求头该怎么写？">
    所有接口统一使用 `Authorization: Bearer sk-...`。JSON 请求再带 `Content-Type: application/json`。例如：

    ```bash
    curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
      -H "Authorization: Bearer sk-你的APIKey" \
      -H "Content-Type: application/json" \
      -d '{ ... }'
    ```
  </Accordion>
  <Accordion title="Base URL 是什么？/api 前缀能省略吗？">
    Base URL 是 `https://api.looprouter.com`，视频接口完整路径是 `/api/v3/contents/generations/tasks`。**`/api` 前缀不能省略**，漏掉会 404。这是从火山方舟迁移时最常见的一个坑，详见 [从方舟迁移](/scenarios/migrate-from-ark)。
  </Accordion>
  <Accordion title="返回 401 Unauthorized 怎么办？">
    401 表示 API Key 缺失或无效。检查：1）请求头是否为 `Authorization: Bearer sk-...`（有 `Bearer ` 前缀、Key 完整）；2）Key 是否被禁用或删除；3）有没有把 Key 写错 / 带上多余空格。到控制台确认令牌状态。
  </Accordion>
  <Accordion title="返回 403 Forbidden 是什么原因？">
    403 有两类常见原因：1）**令牌无权访问该模型**——到控制台确认令牌可用模型范围；2）**内容审核未通过**——最典型的是把真实人脸图片直接放进了生成请求，需先走 [真人认证](/asset-management/real-person)。两者提示信息不同，按 `message` 区分。
  </Accordion>
  <Accordion title="一个令牌多人 / 多进程共用可以吗？">
    可以。同一把 Key 可在多处并发使用，任务与素材都归属于同一账号。注意限流是按账号维度的（见 [并发与限流](/faq/concurrency-and-ratelimit)），多人共用会共享这份额度。出于安全建议不同用途分配不同令牌，方便在日志中区分与单独吊销。
  </Accordion>
  <Accordion title="怀疑 Key 泄露了怎么办？">
    立即到 [控制台 → 令牌](https://console.looprouter.com/keys) 禁用 / 删除该令牌并新建一把，然后更新你的服务配置。素材 ID、真人认证的 `BytedToken` 同样属于敏感凭据，也应一并排查。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    创建 Key 并跑通第一个任务
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    额度与扣费规则
  </Card>
  <Card title="从方舟迁移" icon="arrows-turn-right" href="/scenarios/migrate-from-ark">
    Base URL 与 Key 替换
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/billing-and-balance.md

# 计费、余额与退款

> 预扣结算是怎么算的？哪些情况不扣费？失败任务会退款吗？视频输入折扣是什么？

<AccordionGroup>
  <Accordion title="视频生成是怎么计费的？">
    采用**提交预扣、完成结算**的两段式流程：

    1. **提交预扣**——任务创建成功后，按请求参数（分辨率、时长）预估并预扣一笔额度，日志中心产生一条预扣记录。
    2. **完成结算**——任务成功后按上游返回的实际用量（`usage.total_tokens`，约等于 时长 × 输出宽 × 输出高 × 24 ÷ 1024）重新计算，多退少补。

    各分辨率档位的具体单价以 [控制台「模型广场」与「日志中心」](https://console.looprouter.com) 展示为准。
  </Accordion>
  <Accordion title="哪些情况不扣费？">
    参数校验失败（**400**，如分辨率不在白名单、传了 `callback_url`）与内容审核拒绝（**403**，如真人脸直传）**均不产生费用**。也就是说请求还没进入真正的生成阶段就不会扣钱。
  </Accordion>
  <Accordion title="任务失败了，预扣的额度会退吗？">
    会。任务进入 `failed` 后，已预扣的额度会**自动全额退回**。你只为成功产出的视频付费。
  </Accordion>
  <Accordion title="预扣和实际结算不一致，正常吗？">
    正常。用 `duration: -1`（模型自选时长）或 `ratio: adaptive` 时，提交时只能按估计值预扣，任务成功后以响应中回填的真实时长 / 分辨率结算，多退少补。想让费用完全可预期，就显式指定 `duration` 与 `resolution`。
  </Accordion>
  <Accordion title="VIP 组和补贴组的折扣是怎么生效的？">
    平台按 API Key 所在[分组](/user-groups)自动应用计费倍率，**VIP 组与补贴组的折扣均以商务对接约定为准**。折扣在预扣与结算阶段都会应用，无需额外传参，且可与视频输入折扣叠加。分组同时决定可用的分辨率档位，详见[分组说明](/user-groups)。
  </Accordion>
  <Accordion title="视频输入折扣是什么？要额外传参吗？">
    当请求 `content` 中包含参考视频（`video_url`）时，系统会**自动**应用带视频输入的优惠倍率，**无需额外传参**。这对「参考视频驱动生成」类需求更划算。
  </Accordion>
  <Accordion title="余额不足会怎样？">
    视频生成是预扣费模式，余额不足会在创建阶段直接返回错误，不会入队。请先到 [控制台「钱包」](https://console.looprouter.com) 确认余额充足再提交。
  </Accordion>
  <Accordion title="怎么核对每一笔扣费？">
    到控制台「日志中心」逐条查看：每个任务会有预扣记录，成功后有结算记录（多退少补），失败任务有退款记录。用 `task_id` 可以把 API 侧的任务与日志对应起来。
  </Accordion>
</AccordionGroup>

<Info>
计费口径与 token 折算的更多背景见 [能力总览 → 模型定价](/api-capabilities/seedance2/overview#模型定价)。
</Info>

## 相关文档

<CardGroup cols={3}>
  <Card title="能力总览" icon="circle-info" href="/api-capabilities/seedance2/overview">
    定价与 token 口径
  </Card>
  <Card title="日志与任务查询" icon="list-check" href="/faq/logs-and-tasks">
    日志中心怎么看
  </Card>
  <Card title="分辨率与时长" icon="expand" href="/faq/resolution-ratio-duration">
    影响费用的参数
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/logs-and-tasks.md

# 日志、任务查询与保留

> 怎么查历史任务？日志中心看什么？任务和成片保留多久？如何批量筛选任务

<AccordionGroup>
  <Accordion title="怎么查一个任务的状态和结果？">
    用 `GET /api/v3/contents/generations/tasks/{task_id}`，返回任务的 `status`、`content.video_url`（成功时）、`usage`、`error`（失败时）等。任务记录长期保留，可随时回查。
  </Accordion>
  <Accordion title="怎么批量查 / 筛选任务？">
    用任务列表接口 `GET /api/v3/contents/generations/tasks`，支持分页与过滤：

    | 参数 | 说明 |
    | --- | --- |
    | `page_num` | 页码，默认 1 |
    | `page_size` | 每页数量，默认 20，最大 500 |
    | `filter.status` | 按状态过滤：`queued` / `running` / `succeeded` / `failed` / `cancelled` |
    | `filter.model` | 按模型过滤 |
    | `filter.task_ids` | 按任务 ID 列表过滤 |

    响应为 `{"items": [...], "total": n}`。跑批场景用它集中查状态，比逐个长轮询高效得多。
  </Accordion>
  <Accordion title="任务和成片保留多久？">
    **任务记录**长期保留，可随时回查。但**成片 `video_url` 是约 2 小时有效的临时签名链接**，过期后重新查询任务会得到新链接；建议生成后尽快转存到自己的存储。
  </Accordion>
  <Accordion title="日志中心能看到什么？">
    [控制台「日志中心」](https://console.looprouter.com) 记录每次调用的预扣、结算（多退少补）、退款明细，可用 `task_id` 与 API 侧任务对应。核对费用、排查异常扣费都在这里。
  </Accordion>
  <Accordion title="排队中的任务能取消吗？">
    可以。`DELETE /api/v3/contents/generations/tasks/{task_id}` 能取消 `queued` 状态的任务；已经 `running` 的任务不可取消（返回 400 `invalid_task_status`）。取消成功返回 `{}`。
  </Accordion>
  <Accordion title="任务列表里查不到别人的任务？">
    对。任务、素材、认证会话都绑定账号，跨账号查询会 404。这是账号隔离，属于预期行为。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    任务列表与取消接口
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    扣费记录核对
  </Card>
  <Card title="网络与下载" icon="download" href="/faq/network-and-download">
    链接过期与转存
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/real-person-and-safety.md

# 真人认证与内容安全

> 为什么真人照片不能直接用？活体认证怎么走？内容审核会拦什么？素材如何隔离

<AccordionGroup>
  <Accordion title="为什么真实人脸照片不能直接作参考图？">
    出于**防深度伪造**的硬性要求，真实人脸图片不能直接放进 `image_url`——会被内容审核 **403 拒绝**。必须先完成 [真人认证](/asset-management/real-person)（本人刷脸），把照片上传到认证产生的 `LivenessFace` 素材组，再以 `asset://素材ID` 引用。
  </Accordion>
  <Accordion title="真人认证的流程是怎样的？">
    五步：`CreateVisualValidateSession` 拿到刷脸链接 → 本人手机打开完成活体检测 → 轮询 `GetVisualValidateResult` 拿到真人素材组 → 向该组上传本人照片并等 `Active` → 生成时 `asset://` 引用。全流程 API 化，无需人工审核介入。详见 [真人认证接口](/asset-management/real-person)。
  </Accordion>
  <Accordion title="查询认证结果返回 404，是失败了吗？">
    不是。轮询 `GetVisualValidateResult` 时返回 404 `NotFound.VisualValidateResult` 表示**对方还没刷完脸**，属于正常的「进行中」状态，继续每 3–5 秒轮询即可。真正的失败是 `Result.Status` 为 `failed` / `expired`。
  </Accordion>
  <Accordion title="认证会话有效期多久？过期怎么办？">
    约 **15 分钟**。请在发起后尽快让本人完成刷脸；过期后重新调用 `CreateVisualValidateSession` 生成新会话即可。
  </Accordion>
  <Accordion title="能上传别人的照片吗？">
    不能。只能上传**已完成刷脸认证的本人**清晰照片。向真人组上传其他人的照片会在内容审核阶段失败（素材状态 `Failed`）。请仅对已获得肖像授权的本人发起认证。
  </Accordion>
  <Accordion title="向普通 AIGC 组传真人照片会怎样？">
    会失败。真实人脸必须放进真人认证产生的 `LivenessFace` 组；向普通 `AIGC` 组上传真人照片会在内容审核阶段失败（素材 `Failed`）。AI 生成的虚拟人像 / 动漫角色则可以放进 `AIGC` 组。
  </Accordion>
  <Accordion title="不同账号之间素材是隔离的吗？">
    是。素材、素材组、认证会话都绑定账号，跨账号查询、引用、删除均返回 404。你的素材其他用户无法看到或使用。
  </Accordion>
  <Accordion title="哪些内容会被审核拦截？">
    典型是未认证的真实人脸直传（403）。此外平台对违规、敏感内容也有审核。被 403 拒绝的请求**不扣费**。合规使用（授权真人 + 正常内容）不受影响。
  </Accordion>
</AccordionGroup>

## 相关文档

<CardGroup cols={3}>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    认证全流程 API
  </Card>
  <Card title="素材库 API" icon="images" href="/asset-management/asset-library">
    素材组类型与隔离
  </Card>
  <Card title="真人口播数字人" icon="microphone" href="/scenarios/digital-human">
    真人出镜场景
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/faq/network-and-download.md

# 网络、下载与常见报错

> 视频链接过期怎么办？下载要不要带 Authorization？Python JSON 解析报错怎么修？

<AccordionGroup>
  <Accordion title="成片 video_url 过期了怎么办？">
    `content.video_url` 是约 **2 小时有效的临时签名链接**。过期后重新调用查询接口 `GET /api/v3/contents/generations/tasks/{id}` 会得到新的下载链接。但强烈建议生成后**尽快转存**到自己的对象存储，不要长期依赖这个临时链接。
  </Accordion>
  <Accordion title="下载视频时要带 Authorization 头吗？">
    **不要**。`video_url` 本身是带签名的直链，下载时携带 `Authorization` 头反而可能导致失败。用干净的 GET 请求下载即可。
  </Accordion>
  <Accordion title="Python requests 报 JSON 解析错误 / 响应被截断？">
    在请求头加 **`Accept-Encoding: identity`**。个别网络环境下网关的 gzip 协商会导致 `requests` 解码异常、响应被截断。加这个头强制不压缩即可解决。

    ```python
    headers = {
        "Authorization": "Bearer sk-你的APIKey",
        "Accept-Encoding": "identity",  # 避免 gzip 解码异常
    }
    ```
  </Accordion>
  <Accordion title="请求超时或偶发 5xx？">
    视频生成耗时较长，请给创建 / 查询请求设置合理的超时，并对 5xx 指数退避重试（2s → 4s → 8s）。查询用轮询而非长连接等待。持续性的服务异常可关注 [服务状态](/live/overview)。
  </Accordion>
  <Accordion title="域名 / 路径应该怎么填？">
    Base URL 是 `https://api.looprouter.com`，视频接口路径 `/api/v3/contents/generations/tasks`，素材库 `/api/v3/assets?Action=...&Version=2024-01-01`。`/api` 前缀不能省略。详见 [API Key 与鉴权](/faq/api-key-and-auth)。
  </Accordion>
  <Accordion title="下载慢 / 大文件怎么处理？">
    用流式下载（`stream=True` / 分块写入）避免一次性载入内存，尤其是 `1080p` / `4k` 的长视频。示例见 [素材引用实战](/asset-management/asset-reference) 里的下载代码。
  </Accordion>
</AccordionGroup>

## 常见报错速查

| 现象 | 原因 | 处理 |
| --- | --- | --- |
| 视频 404 下载失败 | `video_url` 已过期（约 2 小时） | 重新查询任务获取新链接，尽快转存 |
| Python JSON 解析异常 / 截断 | 网关 gzip 协商问题 | 请求头加 `Accept-Encoding: identity` |
| 下载 403 | 带了 `Authorization` 头 | 下载直链时去掉鉴权头 |
| 404 找不到接口 | 漏了 `/api` 前缀 | 路径写全 `/api/v3/...` |
| 400 `asset not found or not active` | 素材还在 `Processing` 或 ID 写错 | 先 `GetAsset` 确认 `Active` |

## 相关文档

<CardGroup cols={3}>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    下载与报错速查
  </Card>
  <Card title="API Key 与鉴权" icon="key" href="/faq/api-key-and-auth">
    Base URL 与请求头
  </Card>
  <Card title="并发与限流" icon="gauge-high" href="/faq/concurrency-and-ratelimit">
    重试策略
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/live/overview.md

# 服务状态与实时动态

> LoopRouter 服务运行状态、上游负载与计划内维护公告；遇到异常时的自查与联系方式

本页汇总 LoopRouter 的运行状态与实时动态（故障、上游负载、计划内维护）。历史事件见 [动态归档](/live/archive)。

<Info>
**当前状态：运行正常。** 视频生成、素材库与真人认证接口均可正常调用。如遇异常，请先按下方「自查清单」排查，多数问题是请求侧可自行解决的。
</Info>

## 实时动态

| 时间 | 类型 | 说明 | 状态 |
| --- | --- | --- | --- |
| 2026-07-23 | 功能上线 | 文档站新增「复制页面」与「让 AI 阅读」，支持每页 `.md` 与 `llms.txt` | 已完成 |
| 2026-07-22 | 功能上线 | Seedance 2.0 视频生成、素材库、真人认证接口正式对外 | 运行中 |

> 我们会在这里发布故障播报、上游负载提示与维护窗口。计划内维护通常安排在低峰时段，并尽量做到无感知切换。

## 遇到问题先自查

大部分「调用异常」其实是请求侧可以自行解决的。按顺序排查：

<Steps>
  <Step title="看 HTTP 状态码与 message">
    400 是参数问题、401/403 是鉴权 / 权限 / 审核、404 是资源不存在、429 是限流、5xx 才是服务端异常。对应处理见 [并发、限流与重试](/faq/concurrency-and-ratelimit)。
  </Step>
  <Step title="确认不是已知差异点">
    分辨率档位依[分组](/user-groups)开放（VIP 组含 480p/4k，补贴组 720p/1080p）、不支持 `callback_url`、成功态是 `succeeded`、真人脸需先认证——这些都不是故障。速查 [从方舟迁移](/scenarios/migrate-from-ark) 的差异点清单。
  </Step>
  <Step title="429 / 5xx 指数退避重试">
    2s → 4s → 8s。高并发时任务会短暂排队，不必立刻判定为故障。
  </Step>
  <Step title="仍无法解决">
    携带 `task_id` / `RequestId` 与出错时间，通过 [控制台](https://console.looprouter.com) 工单联系我们，便于快速定位。
  </Step>
</Steps>

## 如何获知服务动态

<CardGroup cols={2}>
  <Card title="本页与归档" icon="wave-pulse" href="/live/archive">
    故障播报、维护窗口与历史事件都会记录在实时动态
  </Card>
  <Card title="最新公告" icon="bullhorn" href="/news/overview">
    新能力上线、计费调整等产品公告
  </Card>
</CardGroup>

<Note>
本页为文档内的状态说明页；权威的实时状态与工单以 [控制台](https://console.looprouter.com) 内展示为准。
</Note>

---

URL: https://docs.looprouter.com/live/archive.md

# 动态归档

> LoopRouter 历史实时动态归档：功能上线、维护窗口与已解决事件

本页归档历史实时动态（已完成 / 已解决的事件）。当前状态与最新动态见 [服务状态](/live/overview)。

## 2026 年 7 月

| 时间 | 类型 | 说明 | 状态 |
| --- | --- | --- | --- |
| 2026-07-23 | 功能上线 | 文档站上线「复制页面」「让 AI 阅读」，新增每页 `.md`、`llms.txt`、`llms-full.txt` | ✅ 已完成 |
| 2026-07-22 | 功能上线 | Seedance 2.0 视频生成 API（文生 / 图生 / 多模态参考）正式对外 | ✅ 已完成 |
| 2026-07-22 | 功能上线 | 素材库 API 与真人认证接口上线，支持角色一致性与真人口播 | ✅ 已完成 |
| 2026-07-22 | 文档 | 文档站 `docs.looprouter.com` 上线，含快速开始与在线调试 | ✅ 已完成 |

<Note>
归档仅保留对接入方有意义的关键事件。计划内维护若无感知切换、且未影响调用，通常不单独归档。
</Note>

## 相关文档

<CardGroup cols={3}>
  <Card title="服务状态" icon="wave-pulse" href="/live/overview">
    当前运行状态与自查
  </Card>
  <Card title="最新公告" icon="bullhorn" href="/news/overview">
    产品能力公告
  </Card>
  <Card title="并发与限流" icon="gauge-high" href="/faq/concurrency-and-ratelimit">
    异常时的重试策略
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/news/overview.md

# 最新公告

> LoopRouter 产品公告：新能力上线、接口更新与计费说明

这里发布 LoopRouter 的产品公告——新能力上线、接口更新与计费说明。服务运行状态与故障动态见 [实时动态](/live/overview)。

<CardGroup cols={1}>
  <Card title="Seedance 2.0 视频生成正式上线" icon="clapperboard" href="/news/seedance-2-0-launch">
    2026-07-22 · 文生 / 图生 / 多模态参考，与火山方舟完全兼容
  </Card>
  <Card title="素材库与真人认证 API 上线" icon="user-check" href="/news/asset-and-real-person-launch">
    2026-07-22 · 角色一致性与真人口播全流程 API 化
  </Card>
  <Card title="携带参考视频自动享受输入折扣" icon="badge-percent" href="/news/video-input-discount">
    2026-07-22 · 请求含 `video_url` 时自动应用优惠倍率
  </Card>
</CardGroup>

<Note>
公告按时间倒序排列，最新在前。想让 AI 跟进文档更新？把 [AI 集成指南](/ai-usage) 里的提示词发给助手即可。
</Note>

---

URL: https://docs.looprouter.com/news/seedance-2-0-launch.md

# Seedance 2.0 视频生成正式上线

> LoopRouter 上线 Doubao Seedance 2.0 视频生成 API：文生 / 图生 / 多模态参考，与火山引擎方舟完全兼容

<Info>
发布日期：2026-07-22
</Info>

LoopRouter 正式对外提供 **Doubao Seedance 2.0** 视频生成能力，接口路径、请求体与响应结构与火山引擎方舟（Ark）**完全一致**，已有的方舟代码只需替换 Base URL 与 API Key 即可迁移。

## 本次上线的能力

<CardGroup cols={2}>
  <Card title="四种生成模式" icon="clapperboard">
    文生视频、首帧图生、首尾帧图生、多模态参考，共用同一接口，靠 `content` 组合区分
  </Card>
  <Card title="多模态参考" icon="layer-group">
    单次最多 9 张参考图 + 3 段参考视频 + 3 段参考音频，锁定角色与风格
  </Card>
  <Card title="音画同步" icon="volume-high">
    `generate_audio` 默认开启，人声 / 音效 / 配乐与画面同步生成
  </Card>
  <Card title="高分辨率" icon="expand">
    支持 `720p` / `1080p` / `4k` 三档输出，固定 24fps
  </Card>
</CardGroup>

## 接口一览

Base URL：`https://api.looprouter.com`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/v3/contents/generations/tasks` | 创建视频生成任务 |
| GET | `/api/v3/contents/generations/tasks/{id}` | 查询单个任务 |
| GET | `/api/v3/contents/generations/tasks` | 任务列表（分页 / 筛选） |
| DELETE | `/api/v3/contents/generations/tasks/{id}` | 取消 / 删除任务 |

## 计费

采用**提交预扣、完成结算**两段式：提交按参数预扣，成功后按实际用量多退少补，失败全额退回；参数校验失败（400）与内容审核拒绝（403）不扣费。详见 [计费与余额](/faq/billing-and-balance)。

## 快速上手

<CardGroup cols={3}>
  <Card title="快速开始" icon="rocket" href="/getting-started">
    三步跑通第一个视频
  </Card>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    全部参数与模式
  </Card>
  <Card title="从方舟迁移" icon="arrows-turn-right" href="/scenarios/migrate-from-ark">
    零成本迁移指南
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/news/asset-and-real-person-launch.md

# 素材库与真人认证 API 上线

> LoopRouter 上线素材库与真人认证接口：角色一致性与真人口播全流程 API 化

<Info>
发布日期：2026-07-22
</Info>

伴随 Seedance 2.0 视频生成，LoopRouter 同步上线**素材库**与**真人认证**两组接口，解决两个高频需求：让多个镜头保持同一角色，以及用真实人物形象合规出镜。

## 素材库：角色一致性

把角色形象注册成素材、拿到长期有效的 `asset-` ID，之后每个镜头都以 `asset://` 引用同一素材，跨镜头保持一致。

<CardGroup cols={2}>
  <Card title="Action 风格接口" icon="images">
    与方舟一致：`POST /api/v3/assets?Action=...&Version=2024-01-01`
  </Card>
  <Card title="两种注册方式" icon="upload">
    公网图片 URL（JSON）或本地文件（multipart），同一把 API Key
  </Card>
</CardGroup>

## 真人认证：合规的真人出镜

出于防深伪要求，真实人脸不能直传。真人认证把「证明是本人授权」全 API 化：

<Steps>
  <Step title="发起认证">`CreateVisualValidateSession` 拿到刷脸 H5 链接</Step>
  <Step title="本人刷脸">手机打开完成活体检测（约 15 分钟有效）</Step>
  <Step title="查询结果">轮询 `GetVisualValidateResult` 拿到真人素材组</Step>
  <Step title="上传并引用">向素材组上传本人照片，生成时 `asset://` 引用</Step>
</Steps>

<Warning>
未经认证的真实人脸图片直接放进生成请求会被内容审核 403 拒绝。合规使用（授权真人）不受影响。
</Warning>

## 上手文档

<CardGroup cols={3}>
  <Card title="素材库 API" icon="images" href="/asset-management/asset-library">
    素材组与素材管理
  </Card>
  <Card title="真人认证接口" icon="user-check" href="/asset-management/real-person">
    认证全流程
  </Card>
  <Card title="素材引用实战" icon="wand-magic-sparkles" href="/asset-management/asset-reference">
    端到端代码
  </Card>
</CardGroup>

---

URL: https://docs.looprouter.com/news/video-input-discount.md

# 携带参考视频自动享受输入折扣

> 请求 content 中包含参考视频（video_url）时，系统自动应用带视频输入的优惠倍率，无需额外传参

<Info>
发布日期：2026-07-22
</Info>

当你的视频生成请求 `content` 中包含**参考视频**（`video_url`）时，LoopRouter 会**自动**应用带视频输入的优惠倍率，**无需额外传参**。这让「参考视频驱动生成」类需求更划算。

## 怎么触发

只要 `content` 数组里带了 `video_url` 类型的内容项，就自动生效：

```json
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "参考视频1的运镜与节奏，生成同风格的城市夜景"},
    {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"}
  ],
  "resolution": "720p",
  "duration": 5
}
```

<Note>
参考视频最多 3 段。多模态参考模式下，参考视频可与参考图、参考音频自由组合（音频不能单独出现，须至少配一张图或一段视频）。
</Note>

## 计费怎么算

折扣叠加在既有的**提交预扣、完成结算**流程上：提交时按参数预扣，任务成功后按实际用量并应用视频输入倍率结算，多退少补。具体单价与倍率以 [控制台「模型广场」与「日志中心」](https://console.looprouter.com) 为准，核对方式见 [计费与余额](/faq/billing-and-balance)。

## 相关文档

<CardGroup cols={3}>
  <Card title="视频生成 API" icon="clapperboard" href="/api-capabilities/seedance2/video-generation">
    content 数组与 role
  </Card>
  <Card title="计费与余额" icon="receipt" href="/faq/billing-and-balance">
    预扣结算规则
  </Card>
  <Card title="角色 IP 与短剧" icon="masks-theater" href="/scenarios/character-ip">
    多模态参考用法
  </Card>
</CardGroup>