Gemini Omni Character 角色生成 API 文档

概述

Gemini Omni Character 角色生成接口，基于一张参考图片创建一个可在视频生成中复用的角色。本接口为同步接口，调用成功后立即返回 characterId，可直接传入 Gemini Omni Video 生视频接口的 characterIds 参数。

Base URL: https://api.apiverse.ai

当前接口为公测能力，暂不计费。

认证方式

Authorization: Bearer {YOUR_AUTH_TOKEN}

快速开始

cURL 示例

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-character" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptions": "一个银白短发、身穿未来风机能夹克的年轻女性角色，冷静、敏捷，具有赛博朋克气质。",
    "imageUrls": ["https://example.com/character-reference.png"],
    "characterName": "珍妮"
  }'

附带语音 ID 创建（让角色拥有指定音色）

curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/gemini-omni-character" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptions": "一个银白短发、身穿未来风机能夹克的年轻女性角色",
    "imageUrls": ["https://example.com/character-reference.png"],
    "audioIds": ["a8f1c2d3e4f5..."],
    "characterName": "珍妮"
  }'

接口列表

1. 创建角色

POST /api/v2/open/aigc/gemini-omni-character

Content-Type: application/json

请求参数

参数	类型	必填	说明
descriptions	string	是	角色描述，用于说明角色的外观、身份、风格、服饰或性格设定
imageUrls	string[]	是	角色参考图片 URL，仅支持 1 张，单张图片大小 ≤ 20MB，需为可公开访问的 URL
audioIds	string[]	否	由生语音接口生成的语音 ID 数组，用于为角色补充声音特征/语气/人设参考
characterName	string	否	角色名称

响应参数

参数	类型	说明
code	int	状态码，0 表示成功
msg	string	状态信息
data.characterId	string	角色 ID，可用于生视频接口的 `characterIds` 参数
data.characterName	string	角色名称
data.imageUrl	string	角色封面图 URL

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": {
    "characterId": "b09dbf56...",
    "characterName": "珍妮",
    "imageUrl": "https://xx.com/a.png"
  }
}

参数错误

{
  "code": 10002,
  "msg": "imageUrls 必须传 1 张图片",
  "data": null
}

创建成功后，该角色会自动保存到你的角色素材库，可通过下方素材管理接口查询和删除。

2. 查询角色素材列表

GET /api/v2/open/omni/character/list

查询当前账号已创建的角色素材（按创建时间倒序）。

请求参数（Query）

参数	类型	必填	说明
page	int	是	页码，从 1 开始
pageSize	int	是	每页数量，1-100
keyword	string	否	按角色名称模糊搜索

cURL 示例

curl -X GET "https://api.apiverse.ai/api/v2/open/omni/character/list?page=1&pageSize=20" \
  -H "Authorization: Bearer your_auth_token_here"

响应参数

参数	类型	说明
data.list	object[]	角色素材列表
data.list[].characterId	string	角色 ID，可用于生视频接口的 `characterIds` 参数
data.list[].characterName	string	角色名称
data.list[].descriptions	string	角色描述
data.list[].imageUrl	string	角色封面图 URL
data.list[].audioIds	string[]	创建时关联的语音 ID
data.list[].createdTime	string	创建时间
data.total	int	总数
data.page	int	当前页
data.pageSize	int	每页数量

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "characterId": "b09dbf56...",
        "characterName": "珍妮",
        "descriptions": "一个银白短发、身穿未来风机能夹克的年轻女性角色",
        "imageUrl": "https://xx.com/a.png",
        "audioIds": ["a8f1c2d3e4f5..."],
        "createdTime": "2026-06-10T15:00:00+08:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

3. 删除角色素材

POST /api/v2/open/omni/character/delete

从素材库中删除指定角色（仅删除素材库记录，不影响已创建的视频任务）。

请求参数

参数	类型	必填	说明
characterId	string	是	要删除的角色 ID

cURL 示例

curl -X POST "https://api.apiverse.ai/api/v2/open/omni/character/delete" \
  -H "Authorization: Bearer your_auth_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "characterId": "b09dbf56..." }'

响应示例

成功

{
  "code": 0,
  "msg": "success",
  "data": null
}

素材不存在

{
  "code": 90003,
  "msg": "角色素材不存在或无权限",
  "data": null
}

错误码

code	说明
0	成功
10002	参数缺失或格式错误
10005	API Key 无效或缺失
30002	上游服务调用失败
90003	服务器内部错误

最佳实践

图片质量：选择面部清晰、光照均匀、构图简洁的参考图，能显著提升角色一致性。
复用 characterId：创建一次角色后保存返回的 characterId，可多次用于不同视频生成任务，保持人设统一；忘记 ID 时可通过素材列表接口找回。
配合生语音接口：先调用生语音接口获取 audioId，再在创建角色时通过 audioIds 关联，可让该角色具备指定音色。
在生视频接口中使用：把返回的 characterId 加入生视频接口的 characterIds 数组；注意配额规则——基础最多 7 个，含源视频时最多 3 个，且需满足 imageUrls + videoList×2 + characterIds ≤ 7。