RootOmni 视频 API 接入说明

测试版只开放 Seedance 2.5。接口地址：https://api.rootomni.com。

鉴权

每次请求添加 Authorization: Bearer YOUR_CUSTOMER_KEY。密钥由我们单独发放，请只保存在自己的服务端，不要放到网页前端、公开代码或截图中。

模型与参数

GET /v1/models 查询当前开放模型，首版模型 ID 为 rootomni-seedance-2-5。

参数	类型	说明
model	string	`rootomni-seedance-2-5`
prompt	string	必填，完整视频提示词，最多40000字符
duration	integer	4至30秒，默认4秒
resolution	string	`480p`、`720p`、`1080p`，默认720p
aspect_ratio	string	`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`
images	string[]	最多30张公网HTTPS图片链接，可省略
videos	string[]	最多10个公网HTTPS视频链接，可省略
audios	string[]	最多10个公网HTTPS音频链接，可省略

参考素材必须无需额外登录就能读取，并在任务结束前保持有效。不能使用本机路径、内网地址、附带账号密码的URL。首版不接收回调地址和任意扩展参数；并发、每日用量由测试账户配额控制。

提交任务

POST /v1/videos，JSON请求体。额外提供 Idempotency-Key 请求头，每次新创作使用一个新值（8至160位英文字母、数字或 ._:-）。网络断开后重试同一次提交，应保留原值和原参数，避免重复生成。

curl https://api.rootomni.com/v1/videos \
  -H "Authorization: Bearer YOUR_CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-video-20261103-001" \
  -d '{"model":"rootomni-seedance-2-5","prompt":"A blue ball rolls slowly across a wooden table, continuous shot, natural daylight.","duration":5,"resolution":"720p","aspect_ratio":"16:9"}'

成功提交返回本站任务编号，例如：

{"id":"rv_0123456789abcdef0123456789abcdef012345","object":"video","model":"rootomni-seedance-2-5","status":"queued","progress":0,"duration":5,"resolution":"720p","aspect_ratio":"16:9","created_at":1793664000}

HTTP 200表示已得到本站任务记录，不等于视频生成成功。必须检查 status 和 error。

查询任务

GET /v1/videos/{id}，使用创建该任务的客户密钥。建议每15至20秒查询一次。

curl https://api.rootomni.com/v1/videos/rv_YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_CUSTOMER_KEY"

status	含义
submitting	正在提交，同一幂等键不能再次创建任务
queued	已排队
in_progress	正在生成
saving	已有生成结果，正在保存视频
completed	完成，`url`和`video_url`为本站下载地址
failed	失败，查看`error.code`及`error.message`

下载视频

completed后使用返回的url，或请求 GET /v1/videos/{id}/content并携带客户密钥。返回的是MP4字节，不会跳转到外部下载地址。支持HEAD及普通Range: bytes=0-1023请求。

返回的签名链接属于临时下载凭据，任何拿到该链接的人均可在有效期内下载。请勿公开。单次链接最长有效1小时，重新鉴权查询任务可取得新链接，但不会超过完成后48小时的视频保存期。务必尽快下载到自己的存储；到期后不保证保留视频。

失败与重试

同一幂等键重复提交只返回同一任务；参数改变返回409。
明确要重新生成时使用新的幂等键，代表一份独立生成请求，可能产生新的费用。不要对超时自动循环创建新任务。
submission_result_unavailable表示没取得完整提交回执，不代表模型一定没接收；系统不会自动重投。人工决定另开一次时才换新幂等键。
429表示账户并发、每日用量或请求频率达到限制；等已有任务结束或联系我们调整配额。
查询/下载其他客户任务返回404；鉴权失败返回401。
测试额度不是正式充值余额，计费标准、失败费用和批量额度由双方确认，不以progress判断扣费。

Python 完整示例

安装requests，设置环境变量ROOTOMNI_API_KEY，下例只创建一个5秒任务。请勿将其放入无限重试循环。

import os, time, uuid, requests

base = "https://api.rootomni.com"
headers = {"Authorization": "Bearer " + os.environ["ROOTOMNI_API_KEY"]}
intent = "demo-" + uuid.uuid4().hex
r = requests.post(base + "/v1/videos", headers={**headers, "Idempotency-Key": intent},
    json={"model": "rootomni-seedance-2-5", "prompt": "A blue ball rolls slowly across a wooden table, natural daylight.",
          "duration": 5, "resolution": "720p", "aspect_ratio": "16:9"}, timeout=330)
r.raise_for_status()
task = r.json()
deadline = time.monotonic() + 1800
while task["status"] not in ("completed", "failed"):
    if time.monotonic() >= deadline:
        raise TimeoutError("Stop polling; retain the task ID and query it later. Do not automatically resubmit.")
    time.sleep(20)
    r = requests.get(base + "/v1/videos/" + task["id"], headers=headers, timeout=75)
    r.raise_for_status()
    task = r.json()
if task["status"] == "failed":
    raise RuntimeError(task.get("error"))
with requests.get(task["url"], stream=True, timeout=180) as video:
    video.raise_for_status()
    with open("rootomni-demo.mp4", "wb") as file:
        for chunk in video.iter_content(1024 * 1024):
            file.write(chunk)
print(task["id"], "completed")