Videos API

AI 视频生成

通过 Videos API 从文字和图片生成视频、查询进度并下载 MP4。

返回文档概览

连接与认证

Base URL: https://caheoai.com/v1

Authorization: Bearer $STALI_API_KEY

设置环境变量 STALI_API_KEY。GET /v1/models 可检查认证,不会生成视频。

read -r -s -p "STALI_API_KEY: " STALI_API_KEY
export STALI_API_KEY
printf '\n'
curl -fsS https://caheoai.com/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"

cURL 命令使用 Bash;Windows 可用 PowerShell 设置密钥。请将示例媒体 URL 替换为供应商可访问的自有文件。

创建视频会计费。成功响应后请保存 id,以便跟踪同一任务。

任务返回 id 后失败时,退款取决于供应商结果及对账;failed 不表示余额已立即退回。

查询、下载和取消不会新建生成任务。取消成功不会自动撤销已记录的费用。

模型与能力

模型Vendor时长(秒)价格 / 视频最多参考图片宽高比分辨率
veo-3.1Google4 / 6 / 8$0.1818 / $0.1818 / $0.18181–316:9, 9:16720p / 1080p
google-omni-flashGoogle5 / 10$0.3636 / $0.36361–316:9, 9:16720p
grok-imagine-video-1.5xAIdocsUpgrade.video.grokDuration$0.4091 / $0.6818 / $1.021–316:9, 9:16, 1:1, 4:3, 3:4720p / 1080p
st1/seedance-2.0-1080pByteDance4–15 seconds (1s steps)Default 5s = $4.480–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:161080p
st1/seedance-2.0-720pByteDance4–15 seconds (1s steps)Default 5s = $1.820–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:16720p
st1/seedance-2.0-fast-720pByteDance4–15 seconds (1s steps, Fast 720p)Default 5s = $1.450–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:16720p
st1/seedance-2.5-1080pByteDance4–30 seconds (1s steps)Default 5s = $6.800–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:161080p
st1/seedance-2.5-720pByteDance4–30 seconds (1s steps)Default 5s = $2.770–10auto / 21:9, 16:9, 4:3, 1:1, 3:4, 9:16720p

veo-3.1 accepts 4/6/8 seconds; google-omni-flash accepts 5/10; grok-imagine-video-1.5 accepts 6/10/15.

图片、尺寸及分辨率支持还取决于供应商线路,并非所有参数适用于所有模型。

veo-3.1 accepts only 4, 6 or 8. google-omni-flash accepts only 5 or 10. grok-imagine-video-1.5 accepts only 6, 10 or 15. Check seconds in the response.

端点与参数

POST /v1/videos — 创建任务

发送 application/json。此端点读取 JSON,不接收 multipart/form-data;请使用模型支持的 URL 或图片 JSON 结构。

参数要求用法
model必填当前上架的视频模型 ID;请明确传入,不要依赖默认模型。
prompt必填描述主体、场景、动作及镜头运动。
seconds可选Follow the model table. veo-3.1 defaults to 8s; google-omni-flash to 10s; grok-imagine-video-1.5 to 6s.
aspect_ratio可选For example 16:9 or 9:16 depending on the model. Keep it consistent with size.
size可选例如 1280x720 或 720x1280;可接受尺寸取决于模型。
images / input_reference可选通过 URL/JSON 传入首帧或参考图。整个请求体上限为 20 MB,另受供应商图片限制。
reference_image_urls可选reference_image_urls: reference images (reference mode; not locked as the first frame).
omni_reference_task_type可选omni_reference_task_type: set "reference" when using reference images with a fixed aspect_ratio.
last_frame可选End frame for veo-3.1 or grok-imagine-video-1.5, with the same input_reference.
input_video可选google-omni-flash 视频转视频的源 MP4 URL。
resolution可选Some models support 720p or 1080p (default 720p). Others may ignore it or derive from size.
generate_audio可选Some video models may ignore generate_audio / reference_audios.

GET /v1/videos/{id} — 查询进度

用 ?model= 指定原始模型。可从每 10 秒查询一次开始,遇 429 时延长间隔。下方 JSON 为示例,并非实时结果。

  • queued:已接收,等待处理。
  • in_progress:供应商正在处理。
  • completed:可请求下载结果。
  • failed:查看 error 并保留 id 以便排查。
{
  "id": "video_abc123",
  "object": "video",
  "model": "st1/seedance-2.0-720p",
  "status": "completed",
  "progress": 100,
  "seconds": "10",
  "size": "1280x720",
  "error": null
}

GET /v1/videos/{id}/content — 下载 MP4

仅在 completed 后下载。传入相同 API 密钥及 ?model=,将二进制响应保存为 .mp4。

DELETE /v1/videos/{id} — 请求取消

取消线路依赖和任务状态;部分线路目前不支持 DELETE。不要将取消命令视为退款承诺。

按时长计费

价格按本站当前配置计算,包含相应调整。创建前请核对。

Seedance duration pricing. Unit: VND per successful video. 4–15s or 4–30s is the supported duration range, not a flat package price. Choose seconds within the supported range; exact prices are listed below. Any fixed generation fee is already included.

st1/seedance-2.0-1080p

If seconds is omitted: 5s = $4.48.

Duration / Seconds价格 / 视频
4s$3.58
5s$4.48
6s$5.38
7s$6.27
8s$7.17
9s$8.06
10s$8.96
11s$9.86
12s$10.75
13s$11.65
14s$12.54
15s$13.44

st1/seedance-2.0-720p

If seconds is omitted: 5s = $1.82.

Duration / Seconds价格 / 视频
4s$1.46
5s$1.82
6s$2.18
7s$2.54
8s$2.90
9s$3.27
10s$3.63
11s$3.99
12s$4.35
13s$4.71
14s$5.08
15s$5.44

st1/seedance-2.0-fast-720p

If seconds is omitted: 5s = $1.45.

Duration / Seconds价格 / 视频
4s$1.16
5s$1.45
6s$1.74
7s$2.03
8s$2.32
9s$2.61
10s$2.90
11s$3.19
12s$3.48
13s$3.77
14s$4.06
15s$4.35

st1/seedance-2.5-1080p

If seconds is omitted: 5s = $6.80.

Duration / Seconds价格 / 视频
4s$5.44
5s$6.80
6s$8.16
7s$9.52
8s$10.88
9s$12.25
10s$13.61
11s$14.97
12s$16.33
13s$17.69
14s$19.05
15s$20.41
16s$21.77
17s$23.13
18s$24.49
19s$25.85
20s$27.21
21s$28.57
22s$29.93
23s$31.29
24s$32.65
25s$34.02
26s$35.38
27s$36.74
28s$38.10
29s$39.46
30s$40.82

st1/seedance-2.5-720p

If seconds is omitted: 5s = $2.77.

Duration / Seconds价格 / 视频
4s$2.22
5s$2.77
6s$3.33
7s$3.88
8s$4.43
9s$4.99
10s$5.54
11s$6.09
12s$6.65
13s$7.20
14s$7.75
15s$8.30
16s$8.86
17s$9.41
18s$9.96
19s$10.52
20s$11.07
21s$11.62
22s$12.18
23s$12.73
24s$13.28
25s$13.83
26s$14.39
27s$14.94
28s$15.49
29s$16.05
30s$16.60

Other video models

模型时长(秒)价格 / 视频
veo-3.14$0.1818
veo-3.16$0.1818
veo-3.18$0.1818
google-omni-flash5$0.3636
google-omni-flash10$0.3636
grok-imagine-video-1.56$0.4091
grok-imagine-video-1.510$0.6818
grok-imagine-video-1.515$1.02

Per-second pricing applies only to duration-priced models (for example grok-imagine-video-1.5). Fixed-price video models use a flat request price.

查看完整价格

集成示例

每次 POST 都会创建收费视频。请选择一个示例,运行前替换 example.com 媒体占位 URL。

import os
import time
from getpass import getpass
from urllib.parse import quote
import requests
from requests.adapters import HTTPAdapter

api_key = os.getenv("STALI_API_KEY") or getpass("STALI_API_KEY: ")
headers = {"Authorization": f"Bearer {api_key}"}
model = "st1/seedance-2.0-720p"
http = requests.Session()
http.mount("https://", HTTPAdapter(max_retries=0))
created = http.post("https://caheoai.com/v1/videos", headers=headers, json={
    "model": model, "prompt": "Cinematic sunset over ocean waves",
    "seconds": 5, "aspect_ratio": "16:9",
}, timeout=(10, 120))
created.raise_for_status()
video = created.json()
video_id = video["id"]
print(video_id, video.get("status"), flush=True)
job_url = "https://caheoai.com/v1/videos/" + quote(video_id, safe="")
for _ in range(120):
    if video.get("status") in ("completed", "failed"):
        break
    time.sleep(10)
    progress = http.get(job_url, headers=headers, params={"model": model}, timeout=(10, 60))
    progress.raise_for_status()
    video = progress.json()
    print(video_id, video.get("status"), flush=True)
if video.get("status") != "completed":
    raise RuntimeError(str(video))
content = http.get(job_url + "/content", headers=headers, params={"model": model}, stream=True, timeout=(10, 120))
content.raise_for_status()
with open("video.mp4", "wb") as output:
    for chunk in content.iter_content(chunk_size=65536):
        if chunk:
            output.write(chunk)

错误处理

HTTP原因处理方式
400参数无效或不支持取消。检查 JSON、seconds、图片及模型支持。
401密钥缺失或无效。检查认证头及有效密钥。
402HTTP 402:检查 error.type、可用余额、密钥限额或此前请求的待补差额。查看 error.type:insufficient_balance → 检查可用余额;api_key_monthly_limit → 在 Dashboard → Keys 检查或调整限额;outstanding_undercharge → 核对并结清此前请求的待补差额。参阅 /docs/reference/errors。
403请求无权限。检查密钥权限、模型及内容政策。
404当前线路找不到模型或任务。使用创建时的 id、密钥和 ?model=。
409任务尚不能执行此操作。继续查询,completed 后再下载。
413请求体超出限制。缩小请求体,用 URL 替代大型内嵌媒体。
429超出频率或并发限制。延长间隔并减少并发任务。
502供应商线路响应错误。保存请求 ID,不要自动重发 POST。

超时或网络错误后不要自动重发 POST,原请求可能已被接收。有 id 时继续查询;没有时请保留请求 ID,检查用量或联系支持后再创建。

提示词设计

以下是创作建议,不保证供应商还原所有细节。各模型的内容政策仍适用。

清晰描述

  1. 先明确主体、场景和主要动作,再添加效果。
  2. 用 seconds 指定时长,不要仅写在提示词里。
  3. 保持镜头间左右位置及服装一致。
  4. 每个镜头优先一种清晰的运镜。
  5. 具体描述光源、颜色和材质。
  6. 避免要求画面中的小字、标志或精确数字。
  7. 先生成短场景,查看后逐项调整。

安排参考图

  • 按提交顺序编号 Image 1、Image 2…。
  • 说明每张图对应人物、服装还是场景。
  • 使用有权使用、清晰且风格一致的图片。
  • 首尾帧人物与构图应相近,使运动自然。
  • 不要超出模型图片上限;参考图不保证完全复现。

提示词模板

确认生成。参数已确定:16:9 横屏,三个连续镜头组成一个完整视频,立即生成,无需再次确认或提问。
The reference images are colored-pencil character design sketches: use them only for design and outfits. Render the video as a photoreal 3D CG game cinematic with dramatic lighting.
Image 1 = PROTAGONIST: [character design].
Image 2 = ANTAGONIST: [opponent design].
Image 3 = ENVIRONMENT: [setting].
FIXED LAYOUT: altar in the background CENTER; protagonist on the LEFT; antagonist on the RIGHT. Nobody disappears, teleports or swaps sides.
LIGHTING: torchlight from the left wall, cool moonlight from the ceiling.
Action: well-choreographed, orbiting camera. No blood, no wounds, no gore.
Sound: heavy impacts, wind, no dialogue.
镜头1: camera pushes in, protagonist draws a weapon, antagonist raises claws.
镜头2: fast exchange, camera orbits.
镜头3: climax, both stay on their sides, protagonist lands ready.
Keep faces and outfits consistent. No text, no numbers, no subtitles, no watermark.

模板用于指导场景。若动作被遗漏请简化,不要用文本替代 API 参数。

描述非血腥动作场景

避免血腥细节更安全的视觉方向
blood, wound, gore, corpsesparks, black smoke, torn fabric only
血泊murky grey mist, dark viscous puddle
造成伤害的攻击glowing wisps of spirit-light, shadowy aura
皮肤伤口tearing only the fabric of the sleeve, no blood

制作多场景序列

  1. 将故事拆成起止明确的场景。
  2. 沿用人物描述、光线和参考图。
  3. 下载检查每个场景后再生成下一段。
  4. 用剪辑工具拼接;每次 POST 仍是单独收费任务。

结果不符时

  • 动作缺失:减少同一场景的事件。
  • 人物换位:明确左右位置并保持构图。
  • 不一致:复用参考图和识别特征描述。
  • 时长错误:检查 seconds 和固定时长模型。
  • 被拒绝:查看 error 及内容政策,不要反复重发相同请求。

用帧网格检查运动

ffmpeg -i clip.mp4 -vf "fps=1,scale=320:-1,tile=6x5" -frames:v 1 frame_grid.png

此 ffmpeg 命令读取本地 clip.mp4 并生成帧网格,不调用 API;需先安装 ffmpeg。

运行前检查

  • 选择正确模型 ID 和支持的时长。
  • 创建前核对价格和余额。
  • 密钥保留在服务端,不放入公开浏览器代码。
  • 使用 JSON 和供应商可访问的媒体 URL。
  • 保存 id、model 及请求 ID。
  • 用 ?model= 查询同一 id,被限流时延长间隔。
  • 仅在 completed 后下载并检查 MP4。
  • 受理状态不明时不要自动重新创建。
  • 在用量页面核对错误与费用,需要时向支持提供 id。
SupportNhóm TelegramWhatsAppViber