视频生成模型

PilotAIHub 视频生成 API 采用异步两阶段模式：提交任务 → 轮询状态，任务完成后系统自动计费，按时长与分辨率计费。

两阶段模式

视频生成为异步任务，两步完成：

提交：POST /v1/videos/generations → 返回任务 ID（零成本占位）
轮询：GET /v1/media/{id}/status → 查询生成状态，任务完成后系统自动计费

1. 提交生成任务

向视频生成端点提交任务，网关返回任务 ID 与初始状态。提交阶段为零成本占位，不扣费。

1.1 Header 参数

参数名	类型	必需	说明
Authorization	string	是	格式为 `Bearer {API_KEY}`，API_KEY 为 PilotAIHub 虚拟 Key。
Content-Type	string	是	固定为 application/json。

1.2 Body 参数

参数名	类型	必需	说明
model	string	是	视频生成模型代码，可通过 GET /v1/models 查询可用模型列表。
prompt	string	是	视频生成提示词，描述希望生成的视频内容。
duration_seconds	integer	否	视频时长（秒），具体可选范围取决于模型支持。
resolution	string	否	视频分辨率，如 "480p"、"720p"、"1080p"、"2k"、"4k"，具体支持取决于模型。

1.3 返回格式

提交响应示例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "provider_task_id": "task-abc123"
}

返回的 id 为任务唯一标识，后续轮询需使用此 ID。

1.4 请求示例

curl

curl https://api.pilotaihub.com/videos/generations \
  -H "Authorization: Bearer sk-p-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "prompt": "A timelapse of a flower blooming",
    "duration_seconds": 5,
    "resolution": "720p"
  }'

python

import requests

resp = requests.post(
    "https://api.pilotaihub.com/videos/generations",
    headers={
        "Authorization": "Bearer sk-p-xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "your-video-model",
        "prompt": "A timelapse of a flower blooming",
        "duration_seconds": 5,
        "resolution": "720p",
    },
)

data = resp.json()
task_id = data["id"]
print(f"Task submitted: {task_id}, status: {data['status']}")

2. 查询任务状态

使用提交时返回的任务 ID 轮询状态，直到状态变为 ready 或 failed。

状态说明

状态值	说明
pending	任务已提交，等待生成中。
ready	生成完成，系统自动计费并返回视频 URL。
failed	生成失败，不会扣费。

返回格式

状态查询响应示例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "media_type": "video",
  "status": "ready",
  "provider_url": "https://cdn.example.com/generated-video-001.mp4",
  "provider_task_id": "task-abc123",
  "created_at": "2026-07-09T10:00:00Z",
  "updated_at": "2026-07-09T10:02:30Z"
}

请求示例

curl

curl https://api.pilotaihub.com/media/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer sk-p-xxxxxxxxxxxxxxxx"

python (轮询示例)

import time
import requests

task_id = "550e8400-e29b-41d4-a716-446655440000"

while True:
    resp = requests.get(
        f"https://api.pilotaihub.com/media/{task_id}/status",
        headers={"Authorization": "Bearer sk-p-xxxxxxxxxxxxxxxx"},
    )
    data = resp.json()
    status = data["status"]
    print(f"Status: {status}")

    if status == "ready":
        print(f"Video URL: {data.get('provider_url')}")
        break
    elif status == "failed":
        print("Generation failed")
        break

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

轮询建议

建议轮询间隔 5-10 秒，视频生成通常需要数十秒到数分钟，取决于时长与分辨率。避免过于频繁的轮询消耗配额。

3. 计费说明

任务状态变为 ready 后，系统自动按视频时长与分辨率计算费用并扣费，不同分辨率单价不同。

计费说明

提交阶段不扣费，仅在任务完成后按实际生成的视频计费。
计费维度：视频时长（秒）× 分辨率单价，不同分辨率价格不同。
生成失败的任务不会产生费用。