動画 API ガイド

動画生成は非同期です。プロンプトと任意の参照素材を送り、タスク ID を保存して状態を照会し、完了後に動画を取得します。HTTP 200 はリクエスト成功であり、生成完了ではありません。

準備とパラメーター

動画マッピングを持つ公共モデルを選び、YOUR_MODEL_ID を置き換えます。サーバーに INONEAPI_API_KEY を設定します。まずテキストのみで確認し、対応パラメーターを追加します。

項目意味
model、prompt必須の公共モデル ID と場面説明。被写体、動き、カメラ、光を指定。
duration任意の整数秒。対応値はモデル次第。
resolution720p/1080p など、対応時のみ。
aspect_ratio16:9/9:16 など。ピクセル寸法ではありません。
input_references任意の image/video/audio と役割。
optionsマッピングが明示対応する拡張のみ。seed や負のプロンプトは共通保証ではありません。
callback_url上流とマッピングが対応する場合のみ。ゲートウェイ自身は通知しません。

作成とポーリング

Node.js 20+ の例は作成後 3 秒間隔で最大 10 分照会します。本番では完全なタスク ID とモデル ID を保存します。再実行時に INONEAPI_VIDEO_TASK_ID を設定すると新規作成せず再開できます。モデルも作成時と同じ値を使います。

curl  https://api.inoneapi.com/v1/videos \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","prompt":"A slow camera movement across a sunlit modern library"}'

非 2xx 時は停止して出力済み ID を保持し、自動再作成しません。照会の 429 は Retry-After、一時的な 5xx は回数を制限した待機後、同じ ID を照会します。全体の期限はモデルに応じて調整します。

タスク状態

status意味動作
queued待機中待って再照会。
running生成中待って再照会。
succeeded完了video_url を確認して保存。
failed失敗停止し error を確認。
cancelledキャンセル済み停止。共通キャンセル API があるとは限りません。
expired期限切れ停止。

状態は上流のマッピングで正規化します。作成時に running の場合もあります。未知の状態はプロトコル問題として扱い、無期限に待機しません。created_at と completed_at はマッピングされている場合 ISO 8601 で、Unix 秒ではありません。

画像から動画・参照素材

Files API で開始フレームをアップロードし、同じキーで送ります。サイズ、秒数、役割はモデルが対応する組み合わせに変更してください。

{
  "model": "YOUR_MODEL_ID",
  "prompt": "Slowly move the camera forward while preserving the reference scene.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "image",
      "role": "first_frame",
      "source": {
        "type": "file",
        "file_id": "file_ioa_0123456789abcdef0123456789abcdef"
      }
    }
  ]
}

開始は first_frame、終了は last_frame、参照は reference、音声は speech を対応時のみ使います。source は file（別名 file_id）、url、data のいずれか 1 つです。ファイル ID は非公開 COS の署名 URL に変換されます。変換処理や上流の役割対応確認は行いません。

公開ファイルは COS 1 日ライフサイクル、署名 URL は 5 分です。有効期間内の読み取りが必要で、上流が読む前に削除しないでください。

タスク ID と権限・経路

新規タスクは ioa_v1. で始まる署名付きハンドルを返します。不透明な文字列として全体を保存し URL エンコードします。解析、切り詰め、上流 ID への置換はしません。同じ model と同じユーザー所有のモデル権限があるキーで照会します。ファイル付き作成はアップロードしたキーが必要です。

ハンドルは作成時のマッピング、上流資格情報、ユーザー、公共モデルに結び付きます。照会はその経路を使い、利用不能でも別プロバイダーへ切り替えません。署名やユーザー・モデル不一致は VIDEO_TASK_NOT_FOUND です。旧形式の生 ID に同等の保証はなく、移行時は元の上流設定を維持します。

結果保存と復旧

上流の video_url は期限切れになる場合があり、永久保存ではありません。自分のストレージへ早めに保存します。外部取得に InOneAPI キーを付けず、ブラウザーでは直接リンクを残します。

作成のタイムアウト時も開始済みの場合があります。一般的な冪等性保証はなく、照会失敗で再度 POST しないでください。ローカル待機停止はキャンセルではありません。モデル、タスク ID、X-Gateway-Trace-ID を保存します。

401/403 は権限、404 はハンドル・所有者・モデル・上流タスク、503 は元のマッピングや資格情報を確認します。共通キャンセル、動画取得プロキシー、コールバック署名・再試行は提供しません。

POST /v1/videos · GET /v1/videos/{id} · POST /v1/files

動画 · ドキュメント · InOneAPI