文档 / 视频生成
API 参考🎬 视频生成

视频生成 API

一套统一请求体调用全部视频模型(Seedance / 可灵 / 海螺 / Vidu / Omni …)。视频要几十秒到几分钟才能生成,所以接口是「先下单、后取货」:提交任务立刻返回单号 task_id,之后每隔几秒查一次(免费),状态变成 completed 就能拿到视频地址 metadata.video_url,也可以直接下载成片。不管背后是哪家渠道,你都只写这一套请求,网关自动翻译。

基址 https://api.aicoming.top(直连、超时 10 分钟)鉴权 Authorization: Bearer sk-…
POST /v1/videos提交生成任务
GET /v1/videos/{id}查询任务 / 取视频地址(免费)
GET /v1/videos/{id}/content下载成片(302 跳转)
旧路径 POST /v1/videos/generations + GET /v1/videos/generations/{task_id} 继续兼容。视频生成耗时数十秒到数分钟,请放宽客户端超时(提交约 120s、轮询约 60s)。

快速开始

第一次用?先做这 4 步(都在控制台完成,约 2 分钟):① 注册登录 → ② 充值几块钱 → ③ 到「商家市场」收藏至少一个商家(智能路由从你收藏的商家里选路,不收藏会报 no_favorited_providers)→ ④ 复制你的「总路由 Key」(API Keys 页顶部),替换下面代码里的 sk-your-key

提交 → 轮询 → 下载,一段代码跑通全流程。本示例 720p × 5 秒约 ¥4.45;想便宜试手,把 model 换成 grok-imagine-1.5-video(¥0.06/秒,5 秒约 ¥0.3),更多低价档见档位手册

import requests, time

BASE = "https://api.aicoming.top/v1"
H = {"Authorization": "Bearer sk-your-key"}

# 1. 提交任务
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "doubao-seedance-2.0",
    "prompt": "海浪拍打礁石,慢镜头,电影质感",
    "resolution": "720p",   # 决定计费档位,不传默认 720p
    "seconds": 5,
}).json()
task_id = task.get("id") or task["data"][0]["task_id"]

# 2. 轮询(免费),完成取视频地址
while True:
    r = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    if r["status"] == "completed":
        print(r["metadata"]["video_url"]); break
    if r["status"] == "failed":
        raise RuntimeError(r)
    time.sleep(3)

# 3.(可选)直接下载成片
open("out.mp4", "wb").write(requests.get(f"{BASE}/videos/{task_id}/content", headers=H).content)

提交参数详解

统一标准请求体——上游不认识的字段会被网关剔除,不会污染请求。

参数类型说明
model必填string

视频模型 ID,以下方档位手册为准。文生/图生视频常为同名模型的 -text-to-video / -image-to-video 两个变体,或同一模型自动按有无 image 切换。

prompt必填string

画面描述 / 运镜指令。图生视频时描述"首帧怎么动"。

resolutionstring

分辨率档位:480p / 720p / 1080p / 2k / 4k(各模型实际可选档见手册)。决定计费档位;不传默认 720p。要更高画质(1080p/2k/4k)请显式传——档位越高单价越高、预扣也越高。也接受 OpenAI 风格 size(如 1280x720,自动映射档位)。兼容位:metadata.resolution(顶层缺失时自动桥接)。

secondsinteger

时长(秒),全局范围 1–600,不传默认 5 秒。别名 duration / n_seconds,兼容 metadata.duration。按秒计费档位 = 单价 × 秒数。各家合法区间不同:seedance 系按代次——2.5 为 4–30 秒、2.0 及更早为 4–15 秒(越界直接 400,不静默修正);可灵 3–15 秒;海螺仅 6/10 秒(自动归一,按归一后秒数计费)。

imagestring

图生视频首帧图:公网可访问 URL(不支持 base64 / data URL)。携带即自动走图生视频。别名 image_url / OpenAI 风格 input_reference

image_tailstring

尾帧图(公网 URL),支持首尾帧的渠道生效,其余忽略。

ratiostring

画面比例:"16:9" / "9:16" / "1:1" 等;仅支持该参数的渠道生效。

audioboolean

是否生成声音;仅支持配音的渠道(如 seedance 2.0)生效。

negative_promptstring

负向提示词;仅支持该参数的渠道生效。

watermarkboolean

是否带 AI 生成水印;仅支持该参数的渠道生效。

referencesarray

参考媒体(seedance 2.0 系),详见下节。与首帧图 image/image_tail 二选一

参考媒体 references(seedance 2.0 系)

最多 9 图 + 3 视频 + 3 音频,按数组顺序对应「图片 1、图片 2…」,prompt 里用 @图片 1 这类别名点名(别名语义由模型理解,网关原样透传 prompt)。所有 url 必须公网可访问,参考媒体不单独计费。

{
  "model": "doubao-seedance-2.0",
  "prompt": "@图片 1 的人物走进 @图片 2 的海滩,背景音乐使用 @音频 1",
  "references": [
    {"media_type": "image", "url": "https://.../person.jpg"},
    {"media_type": "image", "url": "https://.../beach.jpg"},
    {"media_type": "audio", "url": "https://.../bgm.mp3"}
  ],
  "resolution": "720p", "seconds": 8
}

兼容别名:reference_images / images(字符串数组会自动转成 references 图片项)。

渠道家族差异速查

统一请求体在所有模型上通用,但各家族有自己的合法区间与专属能力。挑模型前先对一眼:

家族代表模型注意事项
Seedance 2.5

seedance2.5-*

时长 4–30 秒(越界直接 400);参考媒体上限 50(30 图 + 10 视频 + 10 音频);480p/720p/1080p。

Seedance 2.0

doubao-seedance-2.0-mini/-fast/dreamina-*

时长 4–15 秒(越界直接 400);支持 references 参考媒体(9 图 + 3 视频 + 3 音频,@图片 1 点名)与 audio 配音;480p/720p/1080p 按秒计费。

Omni-Flash-Ext
(APIMart 系)

omni-flash-ext-720p-4s / -1080p-10s / -ref-video-1080p

SKU 名即固定规格:分辨率/时长由模型名决定并按次一口价,请求里传 resolution/seconds 会被 SKU 覆盖。-ref-video 变体传 video_urls 参考视频(与时长互斥,自动去掉 duration)。画幅缺省 16:9,可传 aspect_ratio 覆盖。

Vidu
(APIMart 系)

viduq3

参考主体生成:图/视频参考用 image_urls / video_urls 携带,prompt 里描述主体如何动。档位与单价见下方手册。

可灵 Kling

kling-*

官方直连:时长 3–15 秒;分辨率 720p/1080p/4k;支持 image + image_tail 首尾帧。

海螺 MiniMax

minimax-* / hailuo-*

官方直连:时长仅 6 或 10 秒(1–6 归 6、7–10 归 10,按归一后秒数计费);分辨率 720p/1080p,无 4k。

Grok Imagine

grok-imagine-1.5-video

低单价按秒档;image 首帧图生视频;能力以档位手册为准。

APIMart 系渠道为整体透传(doubao-seedance / dreamina / Omni / viduq3 等):除上面的统一字段外,APIMart 官方文档里的其余字段(如 generation_typeimage_urlsvideo_urls)可直接放进请求体,网关原样转发并自动把数字字符串归一为整型(上游对 seconds/duration 只收数字)。91token 转售的 Vidu 系与雨顺星枢的 APIMart 系,在本平台都收敛为同一套统一请求体,无需分别对接两家原始文档。

Omni 系列详解(APIMart 上游)

Omni-Flash-Ext 是走 APIMart 的一组视频模型,特点是把规格写进模型名:选哪个 SKU 就等于选定了分辨率与时长,价格随之固定。适合"我就要 1080p 的 6 秒片、想提前知道这一条花多少钱"的场景。

SKU 命名规则

Omni-Flash-Ext-1080P-6s        标准生成:1080p、6 秒、按次一口价
Omni-Flash-Ext-Ref-Video-1080P   参考视频:1080p、时长跟随参考视频、按秒计费
Omni-Flash-Ext                    不带后缀的基础款:分辨率/时长自己传,按秒计费

分辨率档 720P / 1080P / 4K,标准生成时长档 4s / 6s / 8s / 10s,两两组合共 12 个固定规格 SKU。

三种用法

用法选哪个模型怎么传
① 固定规格生成

Omni-Flash-Ext-1080P-6s 这类带规格后缀的

只传 model + prompt(图生视频再加 image)即可。请求里的 resolution/seconds 会被 SKU 覆盖——规格由模型名决定,传了也不生效,价格就是该 SKU 的一口价。

② 参考视频生成

Omni-Flash-Ext-Ref-Video-720P/1080P/4K

video_urls(公网视频 URL 数组)作为参考,prompt 描述要怎么改。时长跟随参考视频、不可指定(网关会自动去掉 duration/seconds),按秒计费。

③ 自由规格

基础款 Omni-Flash-Ext

自己传 resolution(720p/1080p/4k)与 seconds,按秒计费:720p/1080p ¥0.644/秒、4K ¥1.932/秒。

价目速查

SKU4s6s8s10s
720P / 1080P

¥2.75

¥3.10

¥3.45

¥3.80

4K

¥6.25

¥6.60

¥6.95

¥7.30

Ref-Video(按秒)

720P / 1080P ¥1.56 每秒 · 4K ¥2.68 每秒(时长 = 参考视频时长)

基础款(按秒)

720p / 1080p ¥0.644 每秒 · 4K ¥1.932 每秒

以上为撰写时价格,档位手册实时数据为准

调用示例

curl https://api.aicoming.top/v1/videos   -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json"   -d '{
    "model": "Omni-Flash-Ext-1080P-6s",
    "prompt": "雨夜霓虹街头,镜头缓慢推进,赛博朋克风格"
  }'
# → {"id":"task_xxx","status":"queued"}   本条固定 ¥3.10

注意事项

  • 固定规格 SKU 传 resolution/seconds 没用:会被模型名里的规格覆盖,计费也按 SKU 一口价。想自选规格请用基础款 Omni-Flash-Ext
  • Ref-Video 不能指定时长:网关会自动移除 duration/seconds(上游对这两者互斥),成片时长 = 参考视频时长,计费按该时长 × 单价。
  • 画幅默认 16:9:显式传 aspect_ratio(或 OpenAI 风格 size)可覆盖。
  • APIMart 官方字段可直接透传generation_typeimage_urlsvideo_urls 等放进请求体即可,网关会把数字字符串归一为整型再转发(上游对时长字段只收数字)。
  • 轮询与其它视频模型完全一致GET /v1/videos/{id},完成后取 metadata.video_url

查询与状态机

GET /v1/videos/{id} 轮询免费,建议间隔 2–5 秒。状态机:

queued(已排队)→ in_progress(生成中)→ completed(完成,metadata.video_url 可取)
                                      ↘ failed(失败,按秒预扣自动退款)
{
  "id": "task_abc123",
  "status": "completed",
  "metadata": {
    "video_url": "https://…/result.mp4",
    "resolution": "720p",
    "seconds": 5
  }
}
结果链接有时效:上游普遍只保留几天(实测部分渠道 3 天后 404)。拿到 video_url 后请及时转存到自己的存储;或直接 GET /v1/videos/{id}/content 由网关代取下载。

计费规则

计费方式规则示例
按秒 per_second

费用 = 所选分辨率档位单价 × 请求秒数。提交时按此预扣,完成后按实际交付多退少补;任务失败自动全额退款

720p ¥0.89/秒 × 5 秒 = ¥4.45

按次 per_call

固定分辨率 + 固定时长整段一口价,请求参数须与档位匹配(不匹配会被拒或按档位规格生成)。

1080p·5s 一口价 ¥2.60/次

两个默认值要心里有数:① 不传 resolution720p 档生成并计费(2026-08-25 前是 1080p);② 不传 seconds 默认生成并计费 5 秒。要多少传多少。轮询与下载不计费。

视频模型档位手册 LIVE

全部在售视频模型逐个的分辨率/时长档位、单价与可运行示例,与线上模型库实时同步。点击展开:

虚拟人物素材(asset:// 引用)

先把人物形象上传为素材,再在视频请求里以 asset://aic_xxx 引用,保持多条视频的人物一致性。完整接口见 API 参考 · 虚拟人物素材库

目前只有 doubao-seedance-2.0 支持 asset:// 引用。同系列的 doubao-seedance-2-0-mini / -fastdreamina-* 系跑在不同的上游后端上,那些后端看不到素材库。对它们传 asset:// 会直接返回 asset_line_unavailable 并说明原因,不会静默生成一个不相干的视频。这些模型要用参考图,改传公网图片地址即可。
先看图片要求,能省掉 90% 的失败:宽和高都要在 300~6000 像素之间,单文件 ≤ 20MB,格式 JPG / PNG / WebP。这是上游模型的硬性门槛——手机截图裁出来的小头像(如 216×384)会被直接判失败,素材状态停在 failed 并在 fail_reason 里写明原因。

三步跑通

第 1 步 · 上传。两种 body 二选一:本地文件用 multipart/form-data,公网图片用 application/json

# 本地文件
curl https://api.aicoming.top/v1/assets \
  -H "Authorization: Bearer sk-your-key" \
  -F "file=@/path/to/face.jpg" -F "name=小美"

# 或者给一个公网地址
curl https://api.aicoming.top/v1/assets \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/face.jpg","name":"小美"}'

返回 201statusprocessing

{"id":"aic_x7KqM3nP8vRt2LwB9cYdZa",
 "asset_url":"asset://aic_x7KqM3nP8vRt2LwB9cYdZa",
 "status":"processing",
 "lines":[{"provider_name":"雨顺星枢 AI","status":"pending"},
          {"provider_name":"91token","status":"pending"}]}

第 2 步 · 轮询到 active上传是异步的:我们要把这张图补传到每条支持素材的线路上。 实测 10 秒内通常就绪。没等到就发起生成会拿到 asset_not_ready

curl https://api.aicoming.top/v1/assets/aic_x7KqM3nP8vRt2LwB9cYdZa \
  -H "Authorization: Bearer sk-your-key"
# → status: processing → active(或 failed,原因见 fail_reason)

lines[] 是各条线路的落地情况。任意一条 active,素材整体就是 active、可以用了; 某条线 failed 不影响使用,生成时会自动挑一条可用的线路。

第 3 步 · 引用生成。asset:// 当成一张参考图,其余参数与普通视频生成完全一致。

两种引用写法

下面两种等价,按你顺手的来。asset:// 也可以和普通图片 URL 混用。

{
  "model": "doubao-seedance-2.0",
  "prompt": "@Image1 的角色在雪山之巅张开双臂",
  "image_urls": ["asset://aic_9f2k71"],
  "resolution": "720p", "duration": 5
}
{
  "model": "doubao-seedance-2.0",
  "prompt": "@图片 1 的人物在雪山之巅张开双臂",
  "references": [{"media_type": "image", "url": "asset://aic_9f2k71"}],
  "resolution": "720p", "seconds": 5
}

多张素材按数组顺序对应提示词里的 @Image1@Image2…… 素材与普通参考图共用同一个 9 张图的上限,不额外放宽。

这一节的常见失败

现象原因与处理

asset_line_unavailable

该模型不支持素材引用(mini / fast / dreamina 系),或素材在可用线路上都还没就绪。换 doubao-seedance-2.0,或改传公网图片地址。

asset_not_ready

上传完没等就发起生成。轮询到 status=active 再发。

asset_invalid_reference

引用格式不对。必须是平台返回的 asset://aic_...,上游原始 ID 一律拒绝。

素材停在 failed

fail_reason。最常见是尺寸越界(宽高需 300~6000px),换一张更大的原图重传。完整错误码见 API 参考 · 错误码

常见错误排查

现象原因与处理

no_favorited_providers

你的账号还没收藏任何商家。去控制台「商家市场」收藏 1 家以上(收藏免费),总路由 Key 会自动覆盖你收藏的全部商家。

402 / insufficient balance

余额不足以预扣本次费用(按秒档 = 档位单价 × 秒数)。充值或改用更低档位/更短时长。

400 duration 越界

seedance 系时长按代次限制:2.5 为 4–30 秒,2.0 及更早为 4–15 秒,越界直接拒绝(刻意不静默修正)。改传合法秒数。

400 分辨率不支持

该模型没有所选档位(如海螺无 4k)。查档位手册选可用档。

400 参考图不可访问

image/references[].url 必须公网可直接 GET;不支持 base64、带鉴权的私有链接、内网地址。

404 unknown or expired video task

task_id 错误、任务过期、或用别人的 Key 查询(任务按账号隔离)。

all upstream candidates failed

该模型全部渠道暂不可用(上游故障/限流)。稍后重试或切换同类模型;按秒预扣已自动退款。

客户端超时 / connection reset

https://api.aicoming.top 直连基址并把客户端超时放宽到 ≥120s;不要用浏览器长连接硬等,改轮询。

asset_line_unavailable

给不支持素材的模型传了 asset://(只有 doubao-seedance-2.0 支持),或素材尚未在任何线路就绪。见虚拟人物素材

asset_not_ready / asset_failed

素材还在补传、或已处理失败。轮询 GET /v1/assets/{id}active;失败时 fail_reason 会写明原因。

最佳实践

  • 显式传 resolution 和 seconds——缺省值(1080p / 5s)是计费口径,不是"自动最便宜"。
  • 参考图先转存公网 URL:上传到自己的对象存储(或用素材库 asset://),别贴带签名参数的临时链接——生成排队期间过期就会失败。
  • 轮询 2–5 秒一次即可,更快没有意义(轮询免费但没必要打满)。
  • 结果及时转存:上游成片链接普遍几天后失效。
  • 失败重试交给路由:同一请求网关会自动在多个渠道间失败切换;收到 all failed 再整体重试即可,不要对单渠道自行密集重试。
  • 按次档位照着档位配参数:固定规格档(如 1080p·5s 一口价)请求里就传该分辨率与时长。