前言

在做内容生产、营销素材或多媒体应用时，我们经常要把"文本/图片 → 视频"和"文本/图片 → 图片"的生成能力接入到自己的服务里。OmniVideo 提供了一套统一的 REST API：用同一套接口就能调度多个底层模型（视频与图像两类），整体走异步任务模式。本文从工程角度梳理完整的对接流程——拿 Key、建任务、轮询结果、错误处理，并给出可直接运行的 Python 代码。

文中用到的 API Key 需要登录官网获取：注册登录后在账户页即可生成。官网地址：Omni Video ，登录后在账户 / API 页面拿到形如 sk-xxxx 的密钥。

一、准备工作：获取 API Key

所有请求都走 Bearer Token 鉴权。登录 Omni Video 账户后，在 API 页面生成密钥，请求头格式为：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

请求基础地址（Base URL）：

https://omnivideo.net/api/v1

二、支持的模型

接口通过 model_id 切换底层模型，目前覆盖视频与图像两类：

model_id	能力	输出
omni-flash	文/图生视频	video_url
omni-pro	文/图生视频	video_url
seedance-2	文/图生视频	video_url
gpt-image-2	文/图生图	image_url
nano-banana-2	文/图生图	image_url

三、核心接口

整个生成是异步任务模型：先提交任务拿到 task_id，再轮询查询结果。

3.1 创建任务

POST /api/v1/tasks/create

请求体字段：

• model_id（必填）：模型标识
• prompt（必填）：生成描述
• image_urls（可选）：输入图片数组，用于图生图 / 图生视频
• aspect_ratio（可选）：画面比例，如 16:9

请求示例：

curl -X POST https://omnivideo.net/api/v1/tasks/create \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "gpt-image-2",
    "prompt": "a serene zen garden at sunrise, ultra detailed",
    "image_urls": [],
    "aspect_ratio": "16:9"
  }'

返回示例：

{
  "code": 200,
  "msg": "提交成功，等待生成",
  "data": {
    "task_id": "abcdef123456",
    "request_id": "kie_xxxxxxxxxxxx",
    "credits": 15
  }
}

提交即扣除积分（credits），任务失败会自动退还，这点对成本控制比较友好。

3.2 查询任务

GET /api/v1/tasks/{task_id}

curl https://omnivideo.net/api/v1/tasks/abcdef123456 \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

返回示例：

{
  "code": 200,
  "msg": "ok",
  "data": {
    "task_id": "abcdef123456",
    "task_status": 3,
    "task_type": "image",
    "model_id": "gpt-image-2",
    "image_url": "https://your-cdn.com/...",
    "video_url": null,
    "audio_url": null,
    "credits": 15,
    "created_at": 1730000000
  }
}

task_status 状态机：

值	含义
1	排队中 queued
2	生成中 running
3	成功 success
4	失败 failed

视频模型取 video_url，图像模型取 image_url。

四、完整对接代码（Python）

把“建任务 + 轮询”封装成一个工具函数，开箱即用：

import time
import requests

BASE_URL = "https://omnivideo.net/api/v1"
API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  # 登录官网获取

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_task(model_id, prompt, image_urls=None, aspect_ratio="16:9"):
    payload = {
        "model_id": model_id,
        "prompt": prompt,
        "image_urls": image_urls or [],
        "aspect_ratio": aspect_ratio,
    }
    resp = requests.post(f"{BASE_URL}/tasks/create", json=payload,
                         headers=HEADERS, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    if data.get("code") != 200:
        raise RuntimeError("创建任务失败: " + str(data.get("msg")))
    return data["data"]["task_id"]


def wait_result(task_id, interval=3, timeout=600):
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}",
                            headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        status = data["task_status"]
        if status == 3:
            return data.get("video_url") or data.get("image_url")
        if status == 4:
            raise RuntimeError("任务生成失败，积分将自动退还")
        time.sleep(interval)
    raise TimeoutError("轮询超时")


if __name__ == "__main__":
    tid = create_task(
        model_id="omni-flash",
        prompt="a cinematic drone shot over a misty mountain valley at dawn",
        aspect_ratio="16:9",
    )
    print("task_id:", tid)
    url = wait_result(tid)
    print("生成结果:", url)

五、错误处理要点

• code 为 200 表示成功，code 为 0 表示业务失败，需读取 msg 定位原因；
• HTTP 401 通常是 Key 无效或没带上 Authorization 头；
• 轮询要设置最大超时与退避间隔，避免空转打满频率；
• 图生视频 / 图生图务必保证 image_urls 是可公网访问的直链。

六、小结

OmniVideo 的接口设计是典型的“提交 - 轮询”异步模型：字段精简、模型可通过 model_id 热切换，接入成本很低，几十行代码就能跑通文 / 图生视频和文 / 图生图。需要 Key 的话，登录 Omni Video 在账户页生成即可，把上面的 Python 封装改改 prompt 和 model_id 就能集成进自己的业务。