API 接口文档

业务接口统一前缀：/api/v1/*，使用 X-App-Key 鉴权

鉴权方式

所有业务接口需在请求头或查询参数中提供 AppKey。

请求头方式（推荐）：X-App-Key: your-appkey 查询参数方式：?appkey=your-appkey

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
appkey	query	string	否	查询参数形式传递 AppKey（与 header 二选一）

POST/api/v1/create

创建数字人视频任务

使用图片和文本/音频驱动生成数字人视频。支持 Vidu 数字人模型（viduq2-turbo）。text 与 audio_url 二选一：text 由平台合成语音再驱动，audio_url 直接使用已有音频驱动。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
image	body	string	是	图片 URL 或 Base64 格式
text	body	string	否	对口型驱动文本（与 audio_url 二选一）
audio_url	body	string	否	对口型音频 URL（与 text 二选一）
voice_id	body	string	否	音色 ID（text 模式时生效，与 voice_name 二选一）
voice_name	body	string	否	音色名称（text 模式时生效，与 voice_id 二选一）
model	body	string	否	模型名，默认 viduq2-turbo
resolution	body	string	否	分辨率：540p / 720p / 1080p，默认 720p
prompt	body	string	否	任务描述，透传给模型
payload	body	string	否	透传参数，原样返回
callback_url	body	string	否	任务完成后的回调地址

请求示例

{
  "image": "https://example.com/face.jpg",
  "text": "你好，我是AI数字人",
  "voice_name": "成熟女声",
  "resolution": "720p"
}

响应示例

{
  "task_id": "915858637757353984",
  "state": "created",
  "image": "https://example.com/face.jpg",
  "text": "你好，我是AI数字人",
  "voice_name": "成熟女声"
}

cURL

curl -X POST "https://your-api-domain.com/api/v1/create" \
  -H "X-App-Key: YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/face.jpg","text":"你好","voice_name":"成熟女声","resolution":"720p"}'

POST/api/v1/image2video/create

创建图生视频任务

使用图片和提示词生成视频。支持 Seedance 系列及 Vidu / Kling / Hailuo / Veo / PixVerse 五大系列模型。

image：Seedance 系列支持 URL 和 Base64；其他模型仅支持公网 URL。model：不传时默认使用 Seedance 旗舰版，系统会根据 model 自动匹配对应服务。模型特有参数直接附加在请求体中透传。

Seedance 系列图片: URL 或 Base64

model 名称	默认时长	说明
doubao-seedance-1-5-pro-251215 (默认)	5s	最新旗舰
doubao-seedance-1-0-pro-250528	5s	稳定版
doubao-seedance-1-0-pro-fast-251015	5s	快速版

Kling 系列（K）图片: 仅 URL 提示词最长 2500 字

model 名称	内部代号	时长(s)	宽高比	特有参数及说明
kling-V1-5	K15	5/10	16:9/9:16/1:1	motionMode(std/pro), cfgScale[0,1]；支持首尾帧/参考生(characterImages≤4)
kling-V1-6	K16	5/10	16:9/9:16/1:1	同 K15
kling-V2-0	K20	5/10	16:9/9:16/1:1	cfgScale，仅支持单图(image必填)
kling-V2-1	K21	5/10	16:9/9:16/1:1	motionMode(std/pro), cfgScale，仅支持单图
kling-V2-1-Master	K21M	5/10	16:9/9:16/1:1	cfgScale，仅支持单图
kling-V2-5-Turbo	K25T	5/10	16:9/9:16/1:1	mode(std/pro), cfgScale，支持首尾帧
kling-V2-6	K26	5/10	16:9/9:16/1:1	mode(仅pro), cfgScale, sound(on/off), voice(on/off), voiceList(≤2)；支持首尾帧+音频合成
kling-O1	KO1	默认5s	16:9/9:16/1:1	mode(std/pro,默认pro), prompt必填,<<<element_1>>>引用主体；不支持单图,支持首尾帧/参考生/主体参考

Vidu 系列（V/VQ）图片: 仅 URL 提示词最长 5000 字

model 名称	内部代号	时长(s)	分辨率	特有参数及说明
vidu2.0	V20	固定4	360p/720p/1080p	aspectRatio, movementAmplitude, audio, bgm；支持首尾帧/参考生/主体参考
viduQ1	VQ1	固定5	仅1080p	aspectRatio, movementAmplitude, audio, bgm；支持首尾帧/参考生/主体参考
viduQ1-classic	VQ1C	固定5	仅1080p	aspectRatio, movementAmplitude, offPeak；仅支持首尾帧模式
viduQ2	VQ2	1-10	360p-1080p	aspectRatio(含3:4/4:3), bgm, offPeak；仅支持参考生模式
viduQ2-turbo	VQ2T	单图1-10/首尾帧1-8	540p-1080p	resolution必填, bgm, offPeak；支持首尾帧/智能多帧
viduQ2-pro	VQ2P	单图1-10/首尾帧1-8	540p-1080p	resolution必填, bgm, offPeak；单图:voiceId；支持首尾帧/参考生/主体参考/智能多帧
viduQ2-pro-fast	VQ2PF	单图1-10/首尾帧1-8	720p/1080p	resolution必填, isRec, bgm, offPeak；单图:audio,voiceId；支持首尾帧

Hailuo 系列（H）图片: 仅 URL 提示词最长 2000 字

model 名称	内部代号	时长(s)	分辨率	特有参数及说明
MiniMax-Hailuo-2.0	H20	6/10	768p/1080p	promptOptimizer(默认true), fastPretreatment, aigcWatermark；1080p仅支持6s；image与headtailImages二选一必填
MiniMax-Hailuo-2.3	H23	6/10	768p/1080p	promptOptimizer, fastPretreatment, aigcWatermark；仅支持单图模式，不支持首尾帧
MiniMax-Hailuo-2.3-Fast	H23F	6/10	768p/1080p	同 H23，不支持首尾帧

PixVerse 系列（P）图片: 仅 URL 提示词最长 2048 字

model 名称	内部代号	时长(s)	分辨率	特有参数及说明
PixVerse-V3.5	P35	5/8	360p-1080p	style, motionMode(normal/fast), soundEffectSwitch；支持首尾帧
PixVerse-V4.0	P40	5/8	360p-1080p	同P35 + cameraMovement(运镜)；支持首尾帧
PixVerse-V4.5	P45	5/8	360p-1080p	同P40，另支持参考生(characterImages)
PixVerse-V5.0	P50	5/8	360p-1080p	style, soundEffectSwitch；motionMode仅normal；支持参考生(≤7张)
PixVerse-V5.5	P55	5/8/10	360p-1080p	style(单图支持), generateAudioSwitch, generateMultiClipSwitch, thinkingType；支持首尾帧

Veo 系列（VE）图片: 仅 URL 提示词最长 2000 字

model 名称	内部代号	时长(s)	分辨率	特有参数及说明
Veo3.1	VE3.1	4/6/8	360p-1080p	prompt必填, generateAudio, n(1-4), personGeneration, seed；支持首尾帧(lastFrame配合image)
Veo3.1-fast	VE3.1F	4/6/8	360p-1080p	prompt必填, n, personGeneration, seed；不支持generateAudio；支持首尾帧

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
image	body	string	是	图片 URL 或 Base64（Seedance 系列支持 Base64，其他模型仅支持 URL）
prompt	body	string	是	Seedance 可附 --duration / --camerafixed 等参数；其他模型直接写描述词
model	body	string	否	模型名称，见上方各系列说明。不传时默认使用 Seedance 旗舰版，系统会根据 model 自动匹配对应服务
duration	body	number	否	视频时长（秒），各模型支持范围见上方说明
resolution	body	string	否	分辨率，各模型支持范围见上方说明
aspectRatio	body	string	否	宽高比：16:9 / 9:16 / 1:1（大多数模型支持）
negativePrompt	body	string	否	负面提示词（部分模型支持）
headtailImages	body	object	否	首尾帧对象 { headImage, tailImage }，支持首尾帧生视频的模型可用
seed	body	number	否	随机种子，控制生成一致性（大部分模型支持）
callback_url	body	string	否	任务完成后的回调地址

请求示例

// Seedance 示例
{
  "image": "https://example.com/photo.png",
  "prompt": "人物缓缓转头微笑 --duration 5",
  "model": "doubao-seedance-1-5-pro-251215"
}

// Kling-2.6（带音频）
{
  "image": "https://example.com/photo.png",
  "prompt": "人物缓缓转头微笑",
  "model": "kling-V2-6",
  "duration": 5,
  "aspectRatio": "16:9",
  "mode": "pro",
  "sound": "on"
}

// PixVerse-4.0（风格+运镜）
{
  "image": "https://example.com/photo.png",
  "prompt": "赛博朋克城市夜景",
  "model": "PixVerse-V4.0",
  "duration": 5,
  "style": "cyberpunk",
  "cameraMovement": "zoom_in"
}

// Vidu Q2 Pro（首尾帧）
{
  "prompt": "角色从左向右行走",
  "model": "viduQ2-pro",
  "headtailImages": {
    "headImage": "https://example.com/start.png",
    "tailImage": "https://example.com/end.png"
  },
  "duration": 5,
  "aspectRatio": "16:9"
}

响应示例

{
  "task_id": "cgt-20260308155446-z8tmx",
  "state": "created",
  "image": "https://example.com/photo.png",
  "prompt": "人物缓缓转头微笑 --duration 5",
  "model": "doubao-seedance-1-5-pro-251215"
}

cURL

# Seedance
curl -X POST "https://your-api-domain.com/api/v1/image2video/create" \
  -H "X-App-Key: YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/photo.png","prompt":"人物转头微笑 --duration 5","model":"doubao-seedance-1-5-pro-251215"}'

# Kling
curl -X POST "https://your-api-domain.com/api/v1/image2video/create" \
  -H "X-App-Key: YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/photo.png","prompt":"人物转头微笑","model":"kling-V2-6","duration":5,"mode":"pro"}'

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

查询图生视频任务状态

根据 task_id 查询图生视频任务状态及生成物 URL。任务状态：created / processing / success / failed。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
task_id	path	string	是	任务 ID

响应示例

{
  "task_id": "cgt-20260308155446-z8tmx",
  "state": "success",
  "creations": [
    { "url": "https://...mp4", "type": "video/mp4" }
  ],
  "resolution": "720p",
  "duration": 5
}

cURL

curl -H "X-App-Key: YOUR_APPKEY" \
  "https://your-api-domain.com/api/v1/image2video/tasks/cgt-20260308155446-z8tmx"

POST/api/v1/audio_tts/create

创建语音合成任务

将文本转换为语音（TTS），支持速度、音量、音调、情绪等可选项。voice_id 和 voice_name 二选一，均不传时使用默认音色。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
text	body	string	是	待合成文本，<10000 字符，支持 <#x#> 停顿标记（x 为秒）
voice_id	body	string	否	音色 ID（与 voice_name 二选一）
voice_name	body	string	否	音色名称（与 voice_id 二选一）
voice_setting_speed	body	number	否	语速，默认 1.0，范围 [0.5, 2.0]
voice_setting_volume	body	number	否	音量，默认 0，范围 [0, 10]
voice_setting_pitch	body	number	否	语调，默认 0，范围 [-12, 12]
voice_setting_emotion	body	string	否	情绪：happy / sad / angry / fearful / disgusted / surprised / calm
pronunciation_dict_tone	body	string	否	多音字标注，如 ['燕少飞/(yan4)(shao3)(fei1)']
payload	body	string	否	透传参数，原样返回，最多 1048576 字符
callback_url	body	string	否	任务完成后的回调地址

请求示例

{
  "text": "大家好，这是一段语音合成测试。",
  "voice_name": "精英青年音色",
  "voice_setting_speed": 1.0,
  "voice_setting_emotion": "calm"
}

响应示例

{
  "task_id": "cgt-xxx",
  "state": "created"
}

cURL

curl -X POST "https://your-api-domain.com/api/v1/audio_tts/create" \
  -H "X-App-Key: YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好世界","voice_name":"精英青年音色","voice_setting_speed":1.0}'

POST/api/v1/audio_clone/create

创建声音复刻任务

根据音频样本复刻自定义音色，复刻完成后可在语音合成中用 voice_id 调用。建议样本 3~15 秒，支持 mp3 / wav / m4a 格式。

voice_id 格式要求：长度 8~256；首字符必须为字母；仅允许字母/数字/_/-；末位不可为 - 或 _；不可与已有 ID 重复。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
audio_url	body	string	是	用于复刻的音频 URL（建议 3~15 秒，支持 mp3/wav/m4a）
voice_id	body	string	是	自定义声音 ID（见格式要求）
voice_name	body	string	否	复刻后的音色展示名称，用于后续 TTS 调用
text	body	string	否	音频对应文本（转录），提升复刻效果
payload	body	string	否	透传参数，最多 1048576 字符

请求示例

{
  "audio_url": "https://your-cdn.com/sample.mp3",
  "voice_id": "myVoice001",
  "voice_name": "我的专属音色",
  "text": "这是音频对应的文本内容"
}

响应示例

{
  "task_id": "cgt-xxx",
  "state": "created"
}

cURL

curl -X POST "https://your-api-domain.com/api/v1/audio_clone/create" \
  -H "X-App-Key: YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"audio_url":"https://your-cdn.com/sample.mp3","voice_id":"myVoice001","text":"对应文本"}'

GET/api/v1/tasks

查询任务列表

查询当前用户的数字人/语音/图生视频任务列表，支持状态、时间、任务 ID 多维度过滤。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
paper_page	query	number	否	页码，从 0 开始，默认 0
paper_pagesz	query	number	否	每页条数，默认 10
states	query	string	否	状态过滤，逗号分隔，如 created,processing,success,failed
task_ids	query	string	否	任务 ID 过滤，逗号分隔
created_at_from	query	string	否	创建时间起始，ISO 8601 格式，如 2026-01-01T00:00:00
created_at_to	query	string	否	创建时间截止，ISO 8601 格式

响应示例

{
  "tasks": [
    {
      "task_id": "915858637757353984",
      "state": "success",
      "created_at": "2026-04-09T06:45:06Z",
      "creation_url": "https://...mp4",
      "creation_cover_url": "https://...jpeg"
    }
  ],
  "total": 100,
  "page": 0,
  "page_size": 10,
  "has_more": true
}

cURL

curl -H "X-App-Key: YOUR_APPKEY" \
  "https://your-api-domain.com/api/v1/tasks?paper_page=0&paper_pagesz=10&states=success"

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

查询任务生成物

获取指定任务的生成物详情（视频/音频 URL）。任务仍在处理中时，creations 为空数组。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
task_id	path	string	是	任务 ID

响应示例

{
  "task_id": "915858637757353984",
  "state": "success",
  "creations": [
    { "url": "https://...mp4", "type": "video/mp4" }
  ],
  "credits_info": {
    "deducted": true,
    "amount": 140,
    "balance": 1380
  }
}

cURL

curl -H "X-App-Key: YOUR_APPKEY" \
  "https://your-api-domain.com/api/v1/tasks/915858637757353984/creations"

GET/api/v1/credits/balance

查询积分余额

获取当前用户积分余额。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey

响应示例

{
  "success": true,
  "credits": 1000,
  "user": {"id": 1, "username": "your-username"}
}

cURL

curl -H "X-App-Key: YOUR_APPKEY" \
  "https://your-api-domain.com/api/v1/credits/balance"

GET/api/v1/credits/records

查询积分记录

获取积分变动记录。

参数名	位置	类型	必填	说明
X-App-Key	header	string	是	业务接口鉴权 AppKey
skip	query	number	否	跳过数量
limit	query	number	否	限制数量

响应示例

{
  "success": true,
  "total": 50,
  "records": [
    {"id": 1, "amount": -10, "reason": "创建数字人任务成功"}
  ]
}

cURL

curl -H "X-App-Key: YOUR_APPKEY" \
  "https://your-api-domain.com/api/v1/credits/records?skip=0&limit=20"