954 lines
26 KiB
Markdown
954 lines
26 KiB
Markdown
# 对外开放模型 API v3 接口文档
|
||
|
||
## 概述
|
||
|
||
本文档描述视频/图片生成平台的对外开放 API v3 接口。外部调用方通过 API Key 认证，调用 AI 视频和图片生成能力。
|
||
|
||
- **Base URL**: `http://your-domain.com/api/v3`
|
||
- **认证方式**: `Authorization: Bearer {api-key}`
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
|
||
---
|
||
|
||
## 认证
|
||
|
||
所有接口均需在请求头中携带 API Key：
|
||
|
||
```
|
||
Authorization: Bearer vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
认证失败时返回：
|
||
|
||
```json
|
||
// 401 API Key 无效或过期
|
||
{
|
||
"error": {
|
||
"code": "invalid_api_key",
|
||
"message": "无效的 API Key"
|
||
}
|
||
}
|
||
|
||
// 429 配额不足
|
||
{
|
||
"error": {
|
||
"code": "quota_exceeded",
|
||
"message": "配额不足 (需要 1.00 元, 剩余 0.50 元)"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 获取可用模型列表
|
||
|
||
获取当前 API Key 可调用的所有视频和图片模型（仅返回已配置价格的模型）。
|
||
|
||
```
|
||
GET /api/v3/models
|
||
```
|
||
|
||
**请求头：**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| Authorization | 是 | `Bearer {api-key}` |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"models": [
|
||
{
|
||
"model": "doubao-seedance-2-0-260128",
|
||
"engine_type": "video",
|
||
"engine_id": "eng_xxxx",
|
||
"supported_ratios": ["16:9", "9:16", "1:1", "4:3"],
|
||
"supported_resolutions": ["480p", "720p", "1080p"],
|
||
"supported_durations": [3, 4, 5, 6, 7, 8, 9, 10, 15]
|
||
},
|
||
{
|
||
"model": "doubao-seedream-5-0-260128",
|
||
"engine_type": "image",
|
||
"engine_id": "eng_yyyy",
|
||
"supported_sizes": ["2K", "4K"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| models | array | 可用模型列表 |
|
||
| models[].model | string | 模型名称 |
|
||
| models[].engine_type | string | 引擎类型: `video` / `image` |
|
||
| models[].engine_id | string | 引擎 ID |
|
||
| models[].supported_ratios | string[] | 视频支持的比例列表 |
|
||
| models[].supported_resolutions | string[] | 视频支持的分辨率列表 |
|
||
| models[].supported_durations | int[] | 视频支持的时长列表(秒) |
|
||
| models[].supported_sizes | string[] | 图片支持的尺寸列表 |
|
||
|
||
---
|
||
|
||
### 2. 创建视频生成任务（异步）
|
||
|
||
创建视频生成任务，接口立即返回 `task_id`，调用方通过轮询查询任务状态和结果。
|
||
|
||
**并发排队机制：**
|
||
- 每个 API Key 可配置最大并发视频任务数（`max_concurrent_video_tasks`）
|
||
- 未超并发：任务立即执行，`status="queued"`
|
||
- 超过并发：任务排队等待，`status="pending_queue"`
|
||
- 当有任务完成/失败时，自动从队列中启动下一个任务
|
||
|
||
```
|
||
POST /api/v3/videos
|
||
```
|
||
|
||
**请求头：**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| Authorization | 是 | `Bearer {api-key}` |
|
||
| Content-Type | 是 | `application/json` |
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"model": "doubao-seedance-2-0-260128",
|
||
"content": [
|
||
{
|
||
"type": "text",
|
||
"text": "一只猫在草地上奔跑"
|
||
},
|
||
{
|
||
"type": "image_url",
|
||
"image_url": {"url": "https://..."},
|
||
"role": "reference_image"
|
||
},
|
||
{
|
||
"type": "video_url",
|
||
"video_url": {"url": "https://..."},
|
||
"role": "reference_video"
|
||
},
|
||
{
|
||
"type": "audio_url",
|
||
"audio_url": {"url": "https://..."},
|
||
"role": "reference_audio"
|
||
}
|
||
],
|
||
"ratio": "16:9",
|
||
"duration": 5,
|
||
"resolution": "1080p",
|
||
"generate_audio": true,
|
||
"watermark": false,
|
||
"idempotency_key": "unique-key-123"
|
||
}
|
||
```
|
||
|
||
**请求字段：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| model | string | 是 | - | 模型名称 |
|
||
| content | array | 是 | - | 生成内容数组（见下方） |
|
||
| ratio | string | 否 | `16:9` | 视频比例: `16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` |
|
||
| duration | int | 否 | `5` | 视频时长(秒): 3-15 |
|
||
| resolution | string | 否 | `480p` | 分辨率: `480p` / `720p` / `1080p` |
|
||
| generate_audio | bool | 否 | `true` | 是否生成音频 |
|
||
| watermark | bool | 否 | `false` | 是否添加水印 |
|
||
| idempotency_key | string | 否 | - | 幂等键，防止重复创建 |
|
||
|
||
**content 数组元素 (ApiVideoContentPart)：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| type | string | 是 | 内容类型: `text` / `image_url` / `video_url` / `audio_url` |
|
||
| text | string | 否 | 文本内容（type=text 时必填） |
|
||
| image_url | object | 否 | 图片URL对象: `{"url": "..."}`（type=image_url 时必填） |
|
||
| video_url | object | 否 | 视频URL对象: `{"url": "..."}`（type=video_url 时必填） |
|
||
| audio_url | object | 否 | 音频URL对象: `{"url": "..."}`（type=audio_url 时必填） |
|
||
| role | string | 否 | 参考角色: `first_frame` / `last_frame` / `reference_image` / `reference_video` / `reference_audio` |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"id": "cgt-20260730183334-wdgfl"
|
||
}
|
||
```
|
||
|
||
**响应字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 任务 ID，用于查询状态 |
|
||
|
||
---
|
||
|
||
### 3. 查询视频任务状态
|
||
|
||
根据 `task_id` 查询视频生成任务的状态和结果。
|
||
|
||
```
|
||
GET /api/v3/videos/{task_id}
|
||
```
|
||
|
||
**请求头：**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| Authorization | 是 | `Bearer {api-key}` |
|
||
|
||
**路径参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| task_id | string | 创建任务时返回的 task_id |
|
||
|
||
**响应示例（排队中）：**
|
||
|
||
```json
|
||
{
|
||
"id": "cgt-20260730183334-wdgfl",
|
||
"model": "doubao-seedance-2-0-mini-260615",
|
||
"status": "queued",
|
||
"created_at": 1785407620,
|
||
"updated_at": 1785407620,
|
||
"content": null,
|
||
"duration": null,
|
||
"ratio": null,
|
||
"resolution": null
|
||
}
|
||
```
|
||
|
||
**响应示例（运行中）：**
|
||
|
||
```json
|
||
{
|
||
"id": "cgt-20260730183334-wdgfl",
|
||
"model": "doubao-seedance-2-0-mini-260615",
|
||
"status": "running",
|
||
"created_at": 1785407620,
|
||
"updated_at": 1785407650,
|
||
"content": null,
|
||
"duration": null,
|
||
"ratio": null,
|
||
"resolution": null
|
||
}
|
||
```
|
||
|
||
**响应示例（成功）：**
|
||
|
||
```json
|
||
{
|
||
"id": "cgt-20260730183334-wdgfl",
|
||
"model": "doubao-seedance-2-0-mini-260615",
|
||
"status": "succeeded",
|
||
"created_at": 1785407620,
|
||
"updated_at": 1785407723,
|
||
"content": {
|
||
"video_url": "https://..."
|
||
},
|
||
"duration": 4,
|
||
"ratio": "9:16",
|
||
"resolution": "480p"
|
||
}
|
||
```
|
||
|
||
**响应示例（失败）：**
|
||
|
||
```json
|
||
{
|
||
"id": "cgt-20260730183334-wdgfl",
|
||
"model": "doubao-seedance-2-0-mini-260615",
|
||
"status": "failed",
|
||
"created_at": 1785407620,
|
||
"updated_at": 1785407650,
|
||
"content": null,
|
||
"duration": null,
|
||
"ratio": null,
|
||
"resolution": null
|
||
}
|
||
```
|
||
|
||
**响应字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | string | 任务 ID |
|
||
| model | string | 模型名称 |
|
||
| status | string | 任务状态（见下方状态说明） |
|
||
| created_at | int | 创建时间戳(Unix) |
|
||
| updated_at | int | 更新时间戳(Unix) |
|
||
| content | object | 视频内容（成功时返回，包含 video_url） |
|
||
| duration | int | 视频时长(秒) |
|
||
| ratio | string | 视频比例 |
|
||
| resolution | string | 分辨率 |
|
||
|
||
**任务状态说明：**
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `queued` | 排队中 |
|
||
| `running` | 任务运行中 |
|
||
| `succeeded` | 任务成功 |
|
||
| `failed` | 任务失败 |
|
||
| `expired` | 任务超时 |
|
||
|
||
---
|
||
|
||
### 4. 生成图片（同步）
|
||
|
||
同步生成图片，接口阻塞等待完成后直接返回结果。
|
||
|
||
```
|
||
POST /api/v3/images
|
||
```
|
||
|
||
**请求头：**
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| Authorization | 是 | `Bearer {api-key}` |
|
||
| Content-Type | 是 | `application/json` |
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"model": "doubao-seedream-5-0-260128",
|
||
"prompt": "一只可爱的猫咪",
|
||
"size": "2K",
|
||
"response_format": "url",
|
||
"watermark": false,
|
||
"image": ["https://example.com/ref1.jpg"],
|
||
"output_format": "png",
|
||
"sequential_image_generation": "auto",
|
||
"generation_count": 1
|
||
}
|
||
```
|
||
|
||
**请求字段：**
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| model | string | 是 | - | 模型名称 |
|
||
| prompt | string | 是 | - | 图片描述提示词 |
|
||
| size | string | 否 | `2K` | 图片尺寸: `2K` / `4K` 或 `2048x2048` |
|
||
| response_format | string | 否 | `url` | 返回格式: `url` / `b64_json` |
|
||
| watermark | bool | 否 | `false` | 是否添加水印 |
|
||
| image | string[] | 否 | - | 参考图片 URL 列表 |
|
||
| output_format | string | 否 | - | 输出格式: `jpeg` / `png` / `webp` |
|
||
| sequential_image_generation | string | 否 | - | 组图模式: `auto` 开启 |
|
||
| generation_count | int | 否 | `1` | 生成数量: 1-5 |
|
||
|
||
**响应示例 (200 OK)：**
|
||
|
||
```json
|
||
{
|
||
"created": 1721000000,
|
||
"data": [
|
||
{
|
||
"url": "https://volc.example.com/image/xxx.png",
|
||
"size": "2K",
|
||
"output_format": "png"
|
||
}
|
||
],
|
||
"model": "doubao-seedream-5-0-260128"
|
||
}
|
||
```
|
||
|
||
**响应字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| created | int | 创建时间戳(Unix) |
|
||
| data | array | 图片结果列表 |
|
||
| data[].url | string | 图片 URL |
|
||
| data[].b64_json | string | Base64 编码图片（response_format=b64_json 时） |
|
||
| data[].size | string | 图片尺寸 |
|
||
| data[].output_format | string | 输出格式 |
|
||
| model | string | 使用的模型名称 |
|
||
|
||
---
|
||
|
||
## 虚拟素材库接口（中转）
|
||
|
||
虚拟素材库用于在**火山方舟私域可信素材服务**中管理专属的图片/视频素材（如客户专属虚拟人）。数据与前台用户私域素材库完全隔离，归属按 API Key 管理。
|
||
|
||
**启用前置条件：**
|
||
1. 管理员在后台「API Key 管理 → 详情 → 虚拟素材库配额」中配置项目数/素材数/存储 MB 上限（默认 0=不可用）
|
||
2. 任一上限大于 0 即表示该 API Key 启用了虚拟素材库功能
|
||
3. 所有操作占用对应配额，超出上限返回 403 `quota_exceeded`
|
||
|
||
**生命周期流程（新，一步到位）：**
|
||
1. 创建虚拟项目（CreateAssetGroup 建远端组）
|
||
2. 直接调用「项目下创建素材」接口，**仅传一个公网可访问的 URL**（http/https 图片/视频直链）
|
||
- 服务端先将该 URL 的文件**下载保存到本地存储系统**（路径见下），占用存储配额
|
||
- 保存成功后，再将**本地公网 URL** 同步提交给火山平台 CreateAsset 做异步审核
|
||
3. 素材状态 Creating → 轮询 `/assets/{id}` 或 `/assets/{id}/sync` 主动刷新 → 状态 Active（可使用）
|
||
4. AI 创作时通过 `/selectable-assets` 选择器拿到已就绪素材
|
||
5. 素材/项目删除（软删本地 + 同步清理本地落盘文件 → 异步删火山远端，返回 `remote_delete_status=pending`）
|
||
|
||
**素材文件本地保存路径（服务端自动处理，调用方无需关心）：**
|
||
- 图片：`/uploads/images/vp_v3_virtual/{api_key_id_short}/yyyy/mm/dd/vp_v3_{uuid}.{ext}`
|
||
- 视频：`/uploads/videos/vp_v3_virtual/{api_key_id_short}/yyyy/mm/dd/vp_v3_{uuid}.{ext}`
|
||
|
||
**技术细节 & 错误处理（保证数据一致性）：**
|
||
1. URL 下载阶段失败（网络/超时/4xx/5xx/大文件/非法 MIME）：立即清理临时文件，不占用任何配额，返回对应错误码
|
||
2. 下载成功但**配额不足**：立即删除已下载的本地文件，释放磁盘，再抛 403 `quota_exceeded`
|
||
3. 视频时长：若请求未传 `video_duration`，服务端自动 ffprobe 探测；两者都失败则删本地文件并 400 要求显式传时长
|
||
4. 本地写库成功但**火山 CreateAsset 失败**：保留本地文件（已占配额和素材数），素材状态标记为 `Failed`，错误信息记录在 `error_message` / `moderation_json`。调用方可选择：
|
||
- 保留并排查（后续可调用 DELETE 删除 → 自动清理本地文件 + 返还配额）
|
||
- 直接 DELETE 重试
|
||
5. 删除素材：**本地 commit 时同步删除本地落盘文件**（目录穿越防御，仅允许删 `/uploads` 目录内），返还存储配额和素材数配额；火山远端异步删除
|
||
|
||
---
|
||
|
||
### 5. 获取配额配置
|
||
|
||
获取当前 API Key 的虚拟素材库配额上限和已使用量，判断是否可用。
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/config
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"project_limit": 5,
|
||
"asset_limit": 50,
|
||
"storage_mb_limit": 500,
|
||
"project_used": 2,
|
||
"asset_used": 18,
|
||
"storage_mb_used": 128.43,
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
**响应字段：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| project_limit | int | 虚拟项目上限，0=不可创建 |
|
||
| asset_limit | int | 虚拟素材总数上限（图片+视频），0=不可上传 |
|
||
| storage_mb_limit | int | 上传存储上限 MB，0=不可上传文件 |
|
||
| project_used | int | 已创建项目数（未删除） |
|
||
| asset_used | int | 已上传素材数（未删除） |
|
||
| storage_mb_used | float | 已占用存储 MB |
|
||
| enabled | bool | 该 Key 是否可使用虚拟素材库功能（任一上限>0即可） |
|
||
|
||
---
|
||
|
||
### 6. 获取枚举元数据
|
||
|
||
返回素材/项目所有枚举值及其说明，便于前端展示筛选选项。
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/enums
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"asset_type": { "Image": "图片素材", "Video": "视频素材" },
|
||
"asset_status": {
|
||
"creating": "创建中/审核中",
|
||
"active": "已就绪/可用",
|
||
"failed": "失败",
|
||
"deleting": "删除中"
|
||
},
|
||
"project_status": {
|
||
"creating_remote_group": "远端组创建中",
|
||
"active": "就绪",
|
||
"create_group_failed": "远端组创建失败",
|
||
"deleting": "删除中"
|
||
},
|
||
"remote_delete_status": {
|
||
"none": "未删除",
|
||
"pending": "待异步删除",
|
||
"processing": "远端删除中",
|
||
"deleted": "远端已删除",
|
||
"failed": "远端删除失败"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 虚拟项目 CRUD
|
||
|
||
#### 7.1 创建项目
|
||
|
||
创建一个虚拟素材项目（同步调火山 CreateAssetGroup 创建远端素材组）。
|
||
|
||
```
|
||
POST /api/v3/virtual-portrait/projects
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"name": "客户A的虚拟人素材",
|
||
"description": "用于客户A的电商视频生成（可选）"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| name | string | 是 | 项目名称，1-100 字符 |
|
||
| description | string | 否 | 项目描述，最多 500 字符 |
|
||
|
||
**响应（VpV3ProjectOut）：**
|
||
|
||
```json
|
||
{
|
||
"Id": "0019xxxxxxxxxxxxxxxx"
|
||
}
|
||
```
|
||
|
||
#### 7.2 查询项目列表
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/projects
|
||
```
|
||
|
||
**Query 参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认 1 |
|
||
| page_size | int | 否 | 每页数量 1-100，默认 20 |
|
||
| keyword | string | 否 | 项目名称模糊搜索 |
|
||
| status | string | 否 | 项目状态筛选（不传查全部） |
|
||
|
||
**响应：** `{ "items": [...], "total": N, "page": X, "page_size": Y }`
|
||
|
||
#### 7.3 项目详情
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/projects/{project_id}
|
||
```
|
||
|
||
#### 7.4 更新项目
|
||
|
||
修改展示信息（名称/描述），不会重新创建火山远端 Group。
|
||
|
||
```
|
||
PUT /api/v3/virtual-portrait/projects/{project_id}
|
||
```
|
||
|
||
#### 7.5 删除项目
|
||
|
||
软删项目和其下所有素材。**本地 commit 后会投递 Celery 异步任务去删除火山远端 AssetGroup/Asset**，接口返回 `remote_delete_status=pending` 表示远端删除处理中，可通过项目详情接口轮询最终状态。
|
||
|
||
```
|
||
DELETE /api/v3/virtual-portrait/projects/{project_id}
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{ "success": true, "remote_delete_status": "pending" }
|
||
```
|
||
|
||
---
|
||
|
||
### 8. 虚拟素材 CRUD
|
||
|
||
#### 8.1 在项目下创建素材
|
||
|
||
创建素材（一步到位：**仅传 URL**：
|
||
1. 服务端先将 `source_url`（公网 http(s)）下载保存到本地存储系统（自动校验 URL/网络/MIME/大小）
|
||
2. 下载成功后占用 **本地存储配额 & 素材数配额
|
||
3. 再将本地公网 URL 同步提交给火山方舟 CreateAsset 进行异步审核
|
||
|
||
```
|
||
POST /api/v3/virtual-portrait/projects/{project_id}/assets
|
||
```
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"source_url": "https://cdn.example.com/avatars/portrait_01.png",
|
||
"name": "虚拟人正面照片",
|
||
"asset_type": "Image"
|
||
}
|
||
```
|
||
|
||
**请求字段（新）：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| source_url | string | 是 | **公网可访问的 http(s) 图片/视频直链**，最多 2000 字符。<br/>⚠️ 不允许指向内网/本机地址（SSRF 防御） |
|
||
| name | string | 否 | 素材展示名，1-100 字符；不传自动从 URL 文件名或响应头 Content-Disposition 推断 |
|
||
| asset_type | string | 是 | `Image` / `Video` |
|
||
| video_duration | float | Video 可选 | 视频时长秒（1-60）。Video 不传会自动 ffprobe 探测，两者都失败则返回 400 需显式传入 |
|
||
| video_cover_url | string | 否（Video） | 视频封面图 URL（可选，仅 Video 用） |
|
||
|
||
> 💡 **不再需要**：`upload_resource_id` / `file_size_bytes` / `mime_type` —— 服务端自动探测并写入。
|
||
|
||
**创建流程时序（服务端内部处理步骤）：**
|
||
1. 校验 URL 格式（http/https + 非内网） → 400
|
||
2. 下载 URL 文件到临时目录
|
||
- HTTP 4xx/5xx → 502（含前 200B 响应片段）；连接/读取超时 → 502
|
||
- Content-Type 非法 → 415（application/octet-stream 除外）；大小超限 → 413
|
||
- 任一步失败：立即清理临时文件，不占配额
|
||
3. 配额校验（素材数 + 存储 MB，按真实大小）→ 不足则删除刚下载的本地文件，403
|
||
4. Video 时长合并校验（payload 优先，否则 ffprobe 探测） → 非法删本地文件并 400
|
||
5. 写 VpV3Asset（status=Creating）+ 刷新 next_poll_at
|
||
6. 调火山 CreateAsset(url=本地公网 URL) → 成功返回 Creating + remote_asset_id；失败则 status=Failed, error_message=错误
|
||
|
||
**响应：VpV3AssetOut**（字段见素材详情）
|
||
|
||
创建成功后 `status=Creating`，火山审核 3-30 秒，建议：
|
||
- 轮询 GET /assets/{id} 或 POST /assets/{id}/sync 主动刷新
|
||
- 直到 status=Active 才能在 AI 创作中使用
|
||
- 如果 status=Failed，读取 `error_message` / `moderation_json` 查看原因；可选择 DELETE 后重试
|
||
|
||
#### 8.2 查询项目下素材列表
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/projects/{project_id}/assets
|
||
```
|
||
|
||
**Query 参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| page / page_size | int | 分页，默认 1/20 |
|
||
| status | string | 素材状态筛选：Creating/Active/Failed/Deleting |
|
||
| keyword | string | 素材名称模糊搜索 |
|
||
| asset_type | string | Image / Video |
|
||
|
||
#### 8.3 素材详情
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/assets/{asset_id}
|
||
```
|
||
|
||
#### 8.4 主动同步素材状态
|
||
|
||
主动调火山 GetAsset 刷新素材状态、URL、审核结果（轮询中断或前端主动刷新时使用）。
|
||
|
||
```
|
||
POST /api/v3/virtual-portrait/assets/{asset_id}/sync
|
||
```
|
||
|
||
#### 8.5 删除素材
|
||
|
||
软删素材。本地 commit 时**同步删除本地落盘文件**（自动清理 `/uploads/...` 目录下的文件，带目录穿越防御），再投递 Celery 异步任务删除火山远端 Asset，返回 `remote_delete_status=pending` 表示处理中。
|
||
|
||
```
|
||
DELETE /api/v3/virtual-portrait/assets/{asset_id}
|
||
```
|
||
|
||
**响应示例：** `{ "success": true, "remote_delete_status": "pending" }`
|
||
|
||
> 说明：
|
||
> - 本地文件删除失败只打日志，不会影响素材状态置为 deleting + soft-delete（避免远端删除也回滚）
|
||
> - 删除成功后存储/素材数配额会自动返还（`/config` 接口再次查询可见 used 降低）
|
||
|
||
---
|
||
|
||
### 9. AI 创作选择器素材
|
||
|
||
只返回当前 API Key 虚拟素材库中 **status=Active** 的图片/视频素材，提供给 AI 创作参考素材选择器使用。
|
||
|
||
```
|
||
GET /api/v3/virtual-portrait/selectable-assets
|
||
```
|
||
|
||
**Query 参数：**
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| page / page_size | int | 分页，默认 1/20（1-100） |
|
||
| project_id | string | 可选，按项目筛选 |
|
||
| keyword | string | 可选，素材名称模糊搜索 |
|
||
| asset_type | string | 可选，Image / Video |
|
||
|
||
**响应字段（VpV3SelectableAssetOut）：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| asset_id | string | 素材 ID，供后续带入生成（预留使用：`source=vp_v3_asset, asset_id`） |
|
||
| project_id | string | 所属项目 ID |
|
||
| name | string | 素材名称 |
|
||
| asset_type | string | Image/Video |
|
||
| status | string | Active |
|
||
| source_url | string | 原始上传 URL |
|
||
| preview_url | string | 显示用预览 URL（直接绑定 img/video src） |
|
||
| video_duration | float | 视频时长秒（Video 时有值） |
|
||
| video_cover_url | string | 视频封面 |
|
||
| file_size_bytes | int | 文件大小字节 |
|
||
| created_at | datetime | 创建时间 |
|
||
|
||
---
|
||
|
||
### 虚拟素材库配额限制错误
|
||
|
||
当 API Key 的虚拟素材库配额不足时，会返回 403：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "quota_exceeded",
|
||
"message": "虚拟素材库配额不足：素材总数 上限 50，已使用 50，本次需要 1，超出上限"
|
||
}
|
||
}
|
||
```
|
||
|
||
如果管理员完全没有配置配额（全 0），任何虚拟素材库操作都返回：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": "forbidden",
|
||
"message": "当前 API Key 未开启虚拟素材库功能，请联系管理员配置配额"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 价格计算规则
|
||
|
||
API 采用**先扣后退回**策略：任务创建/生成前预扣配额，失败时自动退回。
|
||
|
||
### 视频价格公式
|
||
|
||
```
|
||
基础费用 = (base_price + per_second_price × duration) × price_ratio
|
||
|
||
传入视频附加 = (input_video_base_price + input_video_per_second_price × 视频时长) × input_video_ratio
|
||
传入图片附加 = (input_image_base_price + input_image_per_image_price × 图片数量) × input_image_ratio
|
||
|
||
总价格 = 基础费用 + 传入视频附加 + 传入图片附加
|
||
```
|
||
|
||
### 图片价格公式
|
||
|
||
```
|
||
基础费用 = base_price × price_ratio
|
||
|
||
传入图片附加 = (input_image_base_price + input_image_per_image_price × 图片数量) × input_image_ratio
|
||
|
||
总价格 = 基础费用 + 传入图片附加
|
||
```
|
||
|
||
### 价格查找优先级
|
||
|
||
1. 引擎专属规则: `gen_type + engine_id + resolution`
|
||
2. 降级: `gen_type + resolution`（取 base_price 最高的）
|
||
3. 未配置价格的模型不会出现在可用列表中
|
||
|
||
---
|
||
|
||
## 状态码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 202 | 任务已创建（视频接口） |
|
||
| 401 | API Key 无效或缺失 |
|
||
| 403 | API Key 过期或无权限 |
|
||
| 404 | 资源不存在 |
|
||
| 422 | 请求参数校验失败 |
|
||
| 429 | 配额不足或并发超限 |
|
||
| 500 | 服务器内部错误 |
|
||
| 504 | 生成超时（图片接口） |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### cURL 示例
|
||
|
||
```bash
|
||
# 1. 获取可用模型
|
||
curl -X GET http://localhost:8000/api/v3/models \
|
||
-H "Authorization: Bearer vk_xxxxxxxxxxxx"
|
||
|
||
# 2. 创建视频任务
|
||
curl -X POST http://localhost:8000/api/v3/videos \
|
||
-H "Authorization: Bearer vk_xxxxxxxxxxxx" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "doubao-seedance-2-0-260128",
|
||
"content": [{"type": "text", "text": "一只猫在草地上奔跑"}],
|
||
"ratio": "16:9",
|
||
"duration": 5,
|
||
"resolution": "1080p"
|
||
}'
|
||
|
||
# 3. 查询视频状态
|
||
curl -X GET http://localhost:8000/api/v3/videos/{task_id} \
|
||
-H "Authorization: Bearer vk_xxxxxxxxxxxx"
|
||
|
||
# 4. 生成图片
|
||
curl -X POST http://localhost:8000/api/v3/images \
|
||
-H "Authorization: Bearer vk_xxxxxxxxxxxx" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "doubao-seedream-5-0-260128",
|
||
"prompt": "一只可爱的猫咪",
|
||
"size": "2K"
|
||
}'
|
||
```
|
||
|
||
### Python 示例
|
||
|
||
```python
|
||
import requests
|
||
|
||
BASE_URL = "http://localhost:8000/api/v3"
|
||
API_KEY = "vk_xxxxxxxxxxxx"
|
||
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
|
||
|
||
# 获取模型列表
|
||
resp = requests.get(f"{BASE_URL}/models", headers=HEADERS)
|
||
models = resp.json()["models"]
|
||
|
||
# 创建视频任务
|
||
resp = requests.post(f"{BASE_URL}/videos", headers=HEADERS, json={
|
||
"model": "doubao-seedance-2-0-260128",
|
||
"content": [{"type": "text", "text": "一只猫在草地上奔跑"}],
|
||
"ratio": "16:9",
|
||
"duration": 5,
|
||
"resolution": "1080p",
|
||
})
|
||
task_id = resp.json()["task_id"]
|
||
|
||
# 轮询视频状态
|
||
import time
|
||
while True:
|
||
resp = requests.get(f"{BASE_URL}/videos/{task_id}", headers=HEADERS)
|
||
data = resp.json()
|
||
if data["status"] == "completed":
|
||
print(f"视频URL: {data['video_url']}")
|
||
break
|
||
elif data["status"] == "failed":
|
||
print(f"失败: {data['error']}")
|
||
break
|
||
time.sleep(30)
|
||
|
||
# 生成图片
|
||
resp = requests.post(f"{BASE_URL}/images", headers=HEADERS, json={
|
||
"model": "doubao-seedream-5-0-260128",
|
||
"prompt": "一只可爱的猫咪",
|
||
"size": "2K",
|
||
})
|
||
images = resp.json()["data"]
|
||
for img in images:
|
||
print(f"图片URL: {img['url']}")
|
||
```
|
||
|
||
---
|
||
|
||
## HTTP 状态码
|
||
|
||
所有接口 HTTP 状态码固定返回 **200**，业务结果通过响应体中的 `code` 字段判断：
|
||
|
||
| code | 说明 |
|
||
|------|------|
|
||
| 0 | 成功 |
|
||
| 40000 | 请求参数错误 |
|
||
| 40001 | 模型+分辨率未配置价格 |
|
||
| 40100 | API Key 无效或缺失 |
|
||
| 40300 | API Key 过期或无权限 |
|
||
| 40400 | 资源不存在 |
|
||
| 42200 | 参数校验失败 |
|
||
| 42900 | 配额不足或并发超限 |
|
||
| 50000 | 服务器内部错误 |
|
||
| 50400 | 生成超时（图片接口） |
|
||
|
||
---
|
||
|
||
## 统一响应格式
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": { ... },
|
||
"message": "ok"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
{
|
||
"code": 40001,
|
||
"data": null,
|
||
"message": "模型 'eng_xxxx' 在分辨率 '1080p' 下未配置，无法生成"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **配额预扣**: 视频任务创建时预扣配额，失败时自动退回
|
||
2. **并发限制**: 每个 API Key 有最大并发视频任务数限制
|
||
3. **轮询间隔**: 视频任务建议轮询间隔 30 秒（前 10 分钟可缩短至 30 秒，之后逐步增加）
|
||
4. **超时时间**: 视频任务最长 24 小时，超时自动失败并退回配额
|
||
5. **幂等键**: 视频接口支持 `idempotency_key`，相同键重复请求返回同一任务
|
||
6. **图片同步**: 图片接口为同步阻塞调用，建议设置 300 秒超时
|
||
7. **统一格式**: 所有接口 HTTP 状态码固定 200，通过 `code` 字段判断业务结果
|
||
|
||
---
|
||
|
||
## 部署与运维
|
||
|
||
### Celery Worker 启动命令
|
||
|
||
API v3 视频异步生成依赖以下 3 个 Celery 队列：
|
||
|
||
| 队列 | 用途 | 推荐并发 |
|
||
|------|------|---------|
|
||
| `gen_api_create` | 视频任务创建（调用 Volcano Ark SDK） | 2-4 |
|
||
| `gen_api_poll` | 视频状态轮询 | 2-4 |
|
||
| `gen_api_download` | 视频下载与超分 | 2-4 |
|
||
|
||
```bash
|
||
# 启动 API v3 专用 Worker
|
||
celery -A app.tasks.celery_app worker -l info \
|
||
-Q gen_api_create,gen_api_poll,gen_api_download \
|
||
--concurrency=4 -n worker_api@%h
|
||
|
||
# 启动 Beat 调度器（定时恢复任务）
|
||
celery -A app.tasks.celery_app beat -l info
|
||
```
|
||
|
||
### 容灾恢复
|
||
|
||
服务重启后，Worker 会自动触发恢复扫描：
|
||
- 扫描 48 小时内未完成的 `ApiGenerationTask`
|
||
- 重新入队中断的 Celery 任务
|
||
- 每分钟定时扫描（Beat 调度）
|
||
|
||
### 日志目录
|
||
|
||
```
|
||
storage/logs/external/
|
||
├── requests/ # 外部 API 请求/响应日志
|
||
├── models/ # 模型调用日志
|
||
├── upscale/ # 超分轮询日志
|
||
└── errors/ # 错误日志
|
||
```
|