Videos API

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.55 / 8 / 10 / 12 / 15 / 30$0.3182 / $0.4205 / $0.4886 / $0.5795 / $0.7159 / $1.060–916:9, 9:16, 1:1, 4:3, 3:4, 21:9, auto720p / 1080p
seedance-2.5-30s固定 30$2.271–916:9, 9:16, 1:1, 4:3, 3:4720p
seedance-2.5-10s固定 10$1.361–916:9, 9:16, 1:1, 4:3, 3:4720p
seedance-2.55 / 10 / 15 / 20–30$0.1909 / $0.2932 / $0.4295 / $0.63411–1016:9, 9:16, 1:1, 4:3, 3:4720p
seedance-2.0-fast5 / 10 / 15$0.15 / $0.2523 / $0.38861–1016:9, 9:16, 1:1, 4:3, 3:4720p
veo-3.14 / 6 / 8$0.1136 / $0.1136 / $0.11361–316:9, 9:16—
google-omni-flash5 / 10$0.15 / $0.151–316:9, 9:16720p

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.55$0.3182
apivn/seedance-2.58$0.4205
apivn/seedance-2.510$0.4886
apivn/seedance-2.512$0.5795
apivn/seedance-2.515$0.7159
apivn/seedance-2.530$1.06
seedance-2.5-30s30$2.27
seedance-2.5-10s10$1.36
seedance-2.55$0.1909
seedance-2.510$0.2932
seedance-2.515$0.4295
seedance-2.530$0.6341
seedance-2.0-fast5$0.15
seedance-2.0-fast10$0.2523
seedance-2.0-fast15$0.3886
veo-3.14$0.1136
veo-3.16$0.1136
veo-3.18$0.1136
google-omni-flash5$0.15
google-omni-flash10$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密钥缺失或无效。检查认证头及有效密钥。
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。
Support