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-30s30固定$2.271–916:9, 9:16, 1:1, 4:3, 3:4720p
seedance-2.5-10s10固定$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を送信します。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倍になります。他のモデルでは無視されるか、size から換算される場合があります。
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)。固定モデルの料金と時間ベースの料金は、システムの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を保存します。
  • 同じidを?model=付きで確認し、制限時は間隔を延ばします。
  • completed後に取得しMP4を確認します。
  • 受理状況が不明なときは自動で再生成しません。
  • 利用履歴でエラーと料金を照合し、必要ならサポートにidを伝えます。
Support