Skip to main content
视频生成为异步执行任务。调用 POST /v1/videos/generations 提交任务后，接口会立即返回 task_id，您需要使用本接口轮询任务状态，直到视频生成完成后获取结果。由于视频生成耗时较长，请根据下方建议合理设置轮询间隔。

​
接口端点

GET https://geekapis.com/v1/videos/generations/{task_id}

​
路径参数

​
task_id
string
required
视频生成任务 ID，或创建任务时传入的 client_business_id。使用 client_business_id 时，查询范围限定在当前 API Key 所属用户下。

​
响应字段

​
id
string
任务唯一标识符。
​
client_business_id
string
客户侧自定义业务 ID。仅当创建任务时传入 client_business_id 时返回。
​
object
string
对象类型，固定为 generation.task。
​
model
string
本次任务所使用的视频生成模型名称。
​
status
string
任务当前状态，取值如下：
  • queued — 排队等待处理
  • in_progress — 处理中
  • completed — 成功完成
  • failed — 任务失败
​
progress
integer
任务进度百分比，范围 0–100。
​
created_at
integer
任务创建时间（Unix 时间戳）。
​
completed_at
integer
任务完成时间（Unix 时间戳），仅任务完成时返回。
​
expires_at
integer
视频 URL 过期时间（Unix 时间戳），仅任务完成时返回。视频生成结果在完成后 24 小时内有效，请及时下载保存。
​
result.data
array
任务结果数据，仅任务成功完成时返回。
​
error.code
string
错误代码，仅任务失败时返回。
​
error.message
string
错误描述信息，仅任务失败时返回。

​
轮询策略

推荐轮询参数
  • 初始等待：5 秒（视频生成启动时间较长，建议先等待再首次查询）
  • 轮询间隔：10 秒
  • 最大等待时长：600 秒（10 分钟）
  • 典型完成时间：1–5 分钟

​
Python 轮询示例

import time
import requests

def poll_video_task(task_id: str, api_key: str, max_wait: int = 600) -> dict:
    """轮询视频生成任务直到完成或超时"""
    url = f"https://geekapis.com/v1/videos/generations/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    start_time = time.time()

    time.sleep(5)  # 初始等待

    while time.time() - start_time < max_wait:
        resp = requests.get(url, headers=headers).json()
        print(f"状态: {resp['status']}, 进度: {resp.get('progress', 0)}%")

        if resp["status"] == "completed":
            return {
                "url": resp["result"]["data"][0]["url"],
                "format": resp["result"]["data"][0].get("format"),
                "expires_at": resp.get("expires_at"),
            }
        elif resp["status"] == "failed":
            raise Exception(f"生成失败: {resp['error']['message']}")

        time.sleep(10)  # 每 10 秒轮询一次

    raise TimeoutError("任务超时")

​
任务状态说明

状态说明是否终态建议操作
queued任务排队等待处理❌等待 5–10 秒后重试查询
in_progress任务正在处理中❌等待 10–15 秒后重试查询
completed任务成功完成✅从 result.data[0].url 获取视频
failed任务处理失败✅检查 error 字段信息

​
性能建议

视频生成耗时较长，推荐以下最佳实践以提升稳定性和效率：
  1. 使用 Webhook 回调 — 如果平台支持，配置回调 URL 可避免频繁轮询，节省请求配额。
  2. 合理设置轮询间隔 — 建议每 10 秒轮询一次，过于频繁会消耗请求配额并触发频率限制。
  3. 设置超时时间并优雅处理失败 — 长视频生成可能需要 5–10 分钟，请设置合理的超时时间，并对失败情况进行处理和重试。
  4. 及时下载保存视频 — 视频 URL 在生成完成后 24 小时过期，请务必在过期前下载保存至您自己的存储。

​
错误码说明

状态码说明
400请求参数错误
401认证失败
402余额不足
404任务不存在
422参数验证失败
429请求频率超限
500服务器内部错误