IGVS 接口文档

基于当前项目源码生成。API 前缀：/v1/igvs。

目录

1. 通用说明
2. 公共接口
3. 主体（Subject）接口
4. 标签（Tag）接口
5. 任务（Task）接口
6. 公共数据结构
7. 附录

通用说明

基础 URL

{server-host}/v1/igvs

统一响应格式

成功示例：

{
  "code": 200,
  "errorCode": 0,
  "errorMessage": "",
  "data": {}
}

业务失败示例（未登录）：

{
  "code": 200,
  "errorCode": 1,
  "errorMessage": "未登录",
  "data": ""
}

系统异常示例：

{
  "code": 500,
  "errorCode": 0,
  "errorMessage": "积分不足",
  "data": ""
}

常见 errorCode

鉴权

需登录接口须在 Header 或 Query 中携带 token：

Header: token: {登录 token}
Query:  ?token={登录 token}

服务端通过 B 网关 /v1/Passport/Index/getLoginInfo 校验登录态。

账号权限

• 主账号（account > 0）：可查看该 uin 下所有子账号的任务和主体
• 子账号：仅可查看 userId 与自身 accountId 匹配的数据

积分说明

• 创建任务、创建主体会先校验积分余额并 预扣积分
• 任务失败时通过内部回调 自动返还积分
• 创建主体失败时也会 自动返还积分

公共接口

1. 获取模型列表

GET /getModelList

鉴权： 否

Query 参数

响应 data

数组，每项字段如下：

mode 子项：

服务端根据 input.model（展示名）和可选的 input.mode 映射为第三方 Vidu 实际模型名。

2. 获取音色列表

GET /getVoiceList

鉴权： 否

Query 参数

响应 data

按语言分组的数组：

list 每项：

3. 计算价格（积分）

POST /computePrice

鉴权： 是

请求体

响应 data

定价规则摘要：

4. 查询 Vidu 平台积分

GET /getCredits

鉴权： 是

请求参数

无

响应 data

主体（Subject）接口

主体用于「参考生视频」「参考生图」等场景，可绑定图片/视频素材、音色及标签。

5. 获取系统主体列表

GET /subject/getSystemList

鉴权： 否

Query 参数

响应 data

6. 创建个人主体

POST /subject/create

鉴权： 是

请求体

响应 data

返回创建后的主体对象，主要字段：

业务说明：

• 创建前按 subject 类型计算并 预扣积分
• Vidu 创建失败时 自动返还积分
• tagId 须为当前 uin 下有效标签

7. 获取个人主体列表

GET /subject/getPersonalList

鉴权： 是

Query 参数

响应 data

{
  "list": [],
  "total": 0
}

list 每项：

8. 更新个人主体

POST /subject/update

鉴权： 是

请求体

响应 data

更新后的主体 ID（int）。

本地数据库立即更新；Vidu 侧更新为异步执行。

9. 删除个人主体

POST /subject/delete

鉴权： 是

请求体

响应 data

字符串 "删除成功"。

标签（Tag）接口

标签按 uin 隔离，每个主体最多绑定一个标签（tagId 字段）。

10. 创建标签

POST /subject/tag/create

鉴权： 是

请求体

响应 data

{ "id": 1 }

11. 删除标签

POST /subject/tag/delete

鉴权： 是

请求体

响应 data

字符串 "删除成功"。

删除后，关联主体的 tagId 自动置为 0。

12. 获取标签列表

GET /subject/tag/getList

鉴权： 是

Query 参数

响应 data

{
  "list": [
    { "id": 1, "name": "人物" },
    { "id": 2, "name": "场景" }
  ],
  "total": 2
}

任务（Task）接口

任务类型 (type)

任务状态 (state)

通用生成参数校验（checkParam）

以下接口统一校验 input：

• model — 模型展示名称
• prompt — 提示词
• aspect_ratio — 宽高比
• resolution — 分辨率

适用：参考生视频、文生视频、图生视频、参考生图、文生图。

批量生成

13. 参考生视频

POST /task/createReferenceToVideo

鉴权： 是

请求体

响应 data

TaskInfo 对象

14. 文生视频

POST /task/createTextToVideo

鉴权： 是

请求体

响应 data

TaskInfo 对象

15. 图生视频

POST /task/createImageToVideo

鉴权： 是

请求体

路由逻辑：

响应 data

TaskInfo 对象

16. 参考生图

POST /task/createReferenceToImage

鉴权： 是

请求体

服务端将每个主体 subjects[i].images[0] 提取到 images 后调用 Vidu。

响应 data

TaskInfo 对象

17. 文生图

POST /task/createTextToImage

鉴权： 是

请求体

响应 data

TaskInfo 对象

18. 视频增强（超分）

POST /task/upscaleVideo

鉴权： 是

请求体

校验：

• video_url 与 creation_id 至少填一个
• 增强分辨率不能低于原视频分辨率

响应 data

TaskInfo 对象

19. 视频延长

POST /task/extend

鉴权： 是

请求体

响应 data

TaskInfo 对象

20. 取消任务

POST /task/cancel

鉴权： 是

请求体

响应 data

字符串 "取消成功"。

状态变更依赖后续异步回调更新。

21. 获取任务列表

GET /task/getList

鉴权： 是

Query 参数

响应 data

{
  "list": [],
  "total": 0
}

list 为 TaskInfo 数组。

22. 删除任务（软删）

POST /task/delete

鉴权： 是

请求体

逻辑： 软删除指定成品；若该任务下所有成品均已删除，则同时软删除任务。

响应 data

字符串 "删除成功"。

公共数据结构

TaskRequest

Input 对象

SubjectItem（input.subjects 元素）

SubjectRequest

TaskInfo 对象

ViduCreation 对象（成品）

附录

接口一览（22 个对外接口）

分辨率等级对照

请求示例

文生视频

POST /v1/igvs/task/createTextToVideo
Content-Type: application/json
token: your-login-token

{
  "num": 1,
  "input": {
    "model": "Vidu 1.5",
    "mode": "标准模式",
    "prompt": "一只猫在草地上奔跑",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 4
  }
}

创建主体（带标签）

POST /v1/igvs/subject/create
Content-Type: application/json
token: your-login-token

{
  "name": "角色A",
  "images": ["https://example.com/character.jpg"],
  "voice_id": "voice_xxx",
  "tagId": 1
}

按标签筛选主体

GET /v1/igvs/subject/getPersonalList?tagId=1&page=1&num=10
token: your-login-token

视频增强

POST /v1/igvs/task/upscaleVideo
Content-Type: application/json
token: your-login-token

{
  "input": {
    "creation_id": 42,
    "upscale_resolution": "1080p"
  }
}