灵元视频 · 对接文档

海外 Seedance 视频生成 · 多上游官转 · 按秒计费 · 异步任务三步走

官方调用两个分组均为官方上游直转。支持透传两个分组均支持原生协议透传。
分组对外只展示售价，调用方式见下。实际接哪家由你选用的模型名决定。

快速开始

三步：① 拿到你的 API Key（登录平台 → 我的 → API Key）；② 用 Key 提交生成任务，拿到任务号；③ 轮询任务号直到 succeeded，取视频地址。

所有接口基址（Base URL）：

鉴权

所有请求带请求头：

Authorization: Bearer <你的 API Key>
Content-Type: application/json

API Key 以 sk-lv- 开头，是你在灵元的客户 Key，不是任何上游的 Key。

统一调用（推荐）

无论底层是哪家上游，你都用同一套接口。平台按模型名自动路由到对应上游，并处理两家完全不同的任务协议。你不需要关心上游差异。

① 提交任务

# POST {BASE}/v1/video/generations
{
  "model": "doubao-seedance-2-0-fast-260128-sec",   // 模型名见"价格"页
  "prompt": "一只橘猫在雨后屋檐下伸懒腰，电影感光线",
  "duration": 5,                 // 秒
  "resolution": "720p",        // 可选：480p/720p/1080p/2k/4k
  "ratio": "16:9",              // 可选
  "images": []                    // 图生视频：首帧图 URL（http/https）
}

{ "id": "lvt-xxxx", "task_id": "lvt-xxxx", "status": "queued" }

② 查询任务

# GET {BASE}/v1/video/generations/lvt-xxxx
{
  "code": "success",
  "data": {
    "id": "lvt-xxxx",
    "status": "succeeded",       // queued|running|succeeded|failed
    "seconds": 5,
    "cost": 1.93,                 // 实际结算金额（元）
    "result": { "video_url": "https://.../out.mp4" }
  }
}

轮询建议 5 秒一次。视频生成通常 1~5 分钟，长视频/高分辨率更久。

分组一：海外SD官转77折

官方调用支持透传上游为 NewAPI 兼容的视频任务接口（OpenAI 风格）。

项目	内容
模型列表	18 个带分辨率后缀的型号（如 `...-sec`、`...-sec-1080p`、`...-sec-4k`），严格按上游名称上架
分辨率	由模型名后缀决定（名字里带 1080p/4k 等）
计费	按秒（部分按次，见价格页"/次"标记）
任务协议	提交 `POST /v1/video/generations`，字段 `prompt + duration`

用统一调用即可，平台已封装。直连该上游时需携带 duration，否则按秒计费模型会报"无法解析时长"。

分组二：海外SD官转8折

官方调用支持透传上游为火山「豆包视频」原生 OpenAPI（kuaizi 转），与 77 折协议完全不同。

项目	内容
模型列表	4 个基础模型：`doubao-seedance-2-0-260128`（Pro）/ `-2-0-fast-260128`（Fast）/ `-2-0-mini-260615`（Mini）/ `-2-5-260628`（2.5）
分辨率	由参数 `resolution` 控制（不在模型名里）
计费	按秒
任务协议	火山原生 `content[]` 数组；文本要包成 `{type:"text",text}`；图生视频用 `{type:"image_url",image_url:{url}}`
特性	2.5 支持草稿(draft)、视频编辑(edit)、视频延长(extend)、多模态参考

注意：8 折上游的图片/视频 URL 不支持 base64 data URI，必须是 http/https/asset 链接。

用统一调用时，平台会自动把 prompt/images 转成火山的 content[] 结构，你无需手动拼。

透传模式（高级）

两家上游均支持原生协议透传。若你想用上游的全部原生字段（草稿、编辑、延长、多参考图等），在提交时加 "passthrough": true，其余字段原样按该上游的原生协议填写，平台只做鉴权、计费、转发，不改你的 body。

{
  "model": "doubao-seedance-2-5-260628",
  "passthrough": true,
  "content": [{"type":"text","text":"..."}],   // 8折：火山原生 content[]
  "duration": 10, "resolution": "1080p"
}

透传时计费仍按实际时长结算，但请求结构的正确性由你负责。不确定就用上面的统一调用。

计费规则

按秒的模型：提交时按 售价 × 预估时长 冻结余额；任务完成后按实际时长结算，多退少不补（余额为准）。
按次的模型：固定一口价。
任务失败/超时：冻结金额全额退回。
余额不足无法提交。充值请联系管理员。

常见错误

HTTP	含义
401	API Key 缺失或无效
402	余额不足
400	模型不存在/参数非法/该渠道未开放透传
404	任务不存在（或不属于你）
502	上游提交失败（返回 message 为上游原文）

灵元 LINGYUAN · 万流归一，灵元自生