AI 视频生成
通过 Videos API 从文字和图片生成视频、查询进度并下载 MP4。
返回文档概览连接与认证
Base URL: https://apivn.dev/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://apivn.dev/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"cURL 命令使用 Bash;Windows 可用 PowerShell 设置密钥。请将示例媒体 URL 替换为供应商可访问的自有文件。
创建视频会计费。成功响应后请保存 id,以便跟踪同一任务。
任务返回 id 后失败时,退款取决于供应商结果及对账;failed 不表示余额已立即退回。
查询、下载和取消不会新建生成任务。取消成功不会自动撤销已记录的费用。
模型与能力
| 模型 | 时长(秒) | 价格 / 视频 | 最多参考图片 | 宽高比 | 分辨率 |
|---|---|---|---|---|---|
apivn/seedance-2.5 | 5 / 8 / 10 / 12 / 15 / 30 | $0.3182 / $0.4205 / $0.4886 / $0.5795 / $0.7159 / $1.06 | 0–9 | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, auto | 720p / 1080p |
seedance-2.5-30s | 固定 30 | $2.27 | 1–9 | 16:9, 9:16, 1:1, 4:3, 3:4 | 720p |
seedance-2.5-10s | 固定 10 | $1.36 | 1–9 | 16:9, 9:16, 1:1, 4:3, 3:4 | 720p |
seedance-2.5 | 5 / 10 / 15 / 20–30 | $0.1909 / $0.2932 / $0.4295 / $0.6341 | 1–10 | 16:9, 9:16, 1:1, 4:3, 3:4 | 720p |
seedance-2.0-fast | 5 / 10 / 15 | $0.15 / $0.2523 / $0.3886 | 1–10 | 16:9, 9:16, 1:1, 4:3, 3:4 | 720p |
veo-3.1 | 4 / 6 / 8 | $0.1136 / $0.1136 / $0.1136 | 1–3 | 16:9, 9:16 | — |
google-omni-flash | 5 / 10 | $0.15 / $0.15 | 1–3 | 16:9, 9:16 | 720p |
seedance-2.5-10s 和 seedance-2.5-30s 使用名称中的固定时长,其他 seconds 值不会改变时长。
图片、尺寸及分辨率支持还取决于供应商线路,并非所有参数适用于所有模型。
seedance-2.5 接受 5、10、15 或 20–30 范围内的秒数;超出这些组的值会被拒绝。在 20–30 组内,系统可能会归到最接近的 20、25 或 30。apivn/seedance-2.5 只接受 5、8、10、12、15 或 30。检查响应中的 seconds;不要仅根据 prompt 推断时长。
端点与参数
POST /v1/videos — 创建任务
发送 application/json。此端点读取 JSON,不接收 multipart/form-data;请使用模型支持的 URL 或图片 JSON 结构。
| 参数 | 要求 | 用法 |
|---|---|---|
model | 必填 | 当前上架的视频模型 ID;请明确传入,不要依赖默认模型。 |
prompt | 必填 | 描述主体、场景、动作及镜头运动。 |
seconds | 可选 | 根据模型表。seedance-2.5 默认 5 秒;apivn/seedance-2.5 默认 10 秒;固定模型忽略其他 seconds。 |
aspect_ratio | 可选 | 如 16:9 或 9:16,视模型而定。apivn/seedance-2.5 另支持 1:1、4:3、3:4、21:9 与 auto。请与 size 保持一致。 |
size | 可选 | 例如 1280x720 或 720x1280;可接受尺寸取决于模型。 |
images / input_reference | 可选 | 通过 URL/JSON 传入首帧或参考图。整个请求体上限为 20 MB,另受供应商图片限制。 |
last_frame | 可选 | veo-3.1 或 apivn/seedance-2.5(batch-frame)的结束帧,使用相同的 input_reference。 |
input_video | 可选 | google-omni-flash 视频转视频的源 MP4 URL。 |
resolution | 可选 | apivn/seedance-2.5 支持 720p 或 1080p(默认 720p)。1080p 按秒计费 ×2 价格。其他模型可忽略或按尺寸换算。 |
generate_audio | 可选 | apivn/seedance-2.5:generate_audio(默认 true)。可以发送 reference_audios(最多 2 个 URL)。 |
GET /v1/videos/{id} — 查询进度
用 ?model= 指定原始模型。可从每 10 秒查询一次开始,遇 429 时延长间隔。下方 JSON 为示例,并非实时结果。
- queued:已接收,等待处理。
- in_progress:供应商正在处理。
- completed:可请求下载结果。
- failed:查看 error 并保留 id 以便排查。
{
"id": "video_abc123",
"object": "video",
"model": "apivn/seedance-2.5",
"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。不要将取消命令视为退款承诺。
按时长计费
价格按本站当前配置计算,包含相应调整。创建前请核对。
| 模型 | 时长(秒) | 价格 / 视频 |
|---|---|---|
apivn/seedance-2.5 | 5 | $0.3182 |
apivn/seedance-2.5 | 8 | $0.4205 |
apivn/seedance-2.5 | 10 | $0.4886 |
apivn/seedance-2.5 | 12 | $0.5795 |
apivn/seedance-2.5 | 15 | $0.7159 |
apivn/seedance-2.5 | 30 | $1.06 |
seedance-2.5-30s | 30 | $2.27 |
seedance-2.5-10s | 10 | $1.36 |
seedance-2.5 | 5 | $0.1909 |
seedance-2.5 | 10 | $0.2932 |
seedance-2.5 | 15 | $0.4295 |
seedance-2.5 | 30 | $0.6341 |
seedance-2.0-fast | 5 | $0.15 |
seedance-2.0-fast | 10 | $0.2523 |
seedance-2.0-fast | 15 | $0.3886 |
veo-3.1 | 4 | $0.1136 |
veo-3.1 | 6 | $0.1136 |
veo-3.1 | 8 | $0.1136 |
google-omni-flash | 5 | $0.15 |
google-omni-flash | 10 | $0.15 |
Seedance 2.5:20–30 秒档同价,表格显示 30 秒档位。apivn/seedance-2.5 按 5/8/10/12/15/30 各档位单独计费(表格 = 720p;1080p = ×2)。固定模型价格和按时长计价按系统两套独立计算方式执行。
查看完整价格集成示例
每次 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 = "apivn/seedance-2.5"
http = requests.Session()
http.mount("https://", HTTPAdapter(max_retries=0))
created = http.post("https://apivn.dev/v1/videos", headers=headers, json={
"model": model, "prompt": "Cinematic sunset over ocean waves",
"seconds": 10, "aspect_ratio": "16:9", "resolution": "720p",
"generate_audio": True,
}, 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://apivn.dev/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 | 密钥缺失或无效。 | 检查认证头及有效密钥。 |
| 402 | HTTP 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,检查用量或联系支持后再创建。
提示词设计
以下是创作建议,不保证供应商还原所有细节。各模型的内容政策仍适用。
清晰描述
- 先明确主体、场景和主要动作,再添加效果。
- 用 seconds 指定时长,不要仅写在提示词里。
- 保持镜头间左右位置及服装一致。
- 每个镜头优先一种清晰的运镜。
- 具体描述光源、颜色和材质。
- 避免要求画面中的小字、标志或精确数字。
- 先生成短场景,查看后逐项调整。
安排参考图
- 按提交顺序编号 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, corpse | sparks, 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 |
制作多场景序列
- 将故事拆成起止明确的场景。
- 沿用人物描述、光线和参考图。
- 下载检查每个场景后再生成下一段。
- 用剪辑工具拼接;每次 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。

