88API88API
使用ガイドAIアプリケーションAPIリファレンスヘルプとサポート
ビデオ(Video)

動画 API 完全呼び出し仕様

88API 統一動画生成 API 仕様。

このページは 88API の統一動画生成仕様で、88API が提供する各種動画モデルに適用されます。自分の API キーで参照できるモデル一覧から model ID を取得し、このページの統一 API を使うだけで呼び出せます。

現在、動画タスクはすべて「モデル取得 → 作成 → ポーリング → ダウンロード」という共通のプロトコルを使います。アカウントによって表示されるモデル ID は異なる場合があり、モデルごとに対応する長さ、アスペクト比、解像度、参照素材の数も異なります。あるモデルの機能をそのまま別のモデルに当てはめないでください。

2026-11-13 更新。各ブランドのモデル固有パラメーターと例は個別ページに分割しました。下記のブランド別の呼び出し仕様を参照してください。推奨フロー:まず GET /v1/models を呼び出して現在のキーで使えるモデル ID を取得します。利用可能な HTTPS 素材があればそのまま参照し、ローカル素材は先にアップロード → 生成を作成 → ポーリングで結果 URL を取得 → 再生・ダウンロード、または次の生成の参照素材として利用します。アップロードに成功しても、モデルがその素材の種類に対応しているとは限りません。モデルの機能とストレージの機能は別物です。

統一的な接続ルール:まず GET /v1/models が返す正確な id を model に指定し、POST /v1/videos でタスクを作成します。レスポンスの id を保存し、GET /v1/videos/{id} でポーリングしてください。新規の接続では旧 /v1/video/generations を使わず、task_id にも依存しないでください。すべての動画モデルはポーリングで結果を取得します。callback_url は設定しないでください。

1. 統一的な接続のための最小ルール

同じクライアントで複数の動画モデルに接続する場合は、次の手順を固定するだけで済みます。

  1. 現在の API キーで GET /v1/models をリクエストします。
  2. 返された結果から、自分のアカウントが実際に権限を持つモデルの id を選びます。モデルマーケットの表示名、旧名称、他のアカウントで表示される名前をグローバル設定にハードコードしないでください。
  3. 同じ POST /v1/videos のリクエスト形式でタスクを作成します。
  4. タスクの照会には、レスポンスで返された公開 id だけを使います。それ以外のタスク ID を解析したり組み立てたりしないでください。
  5. 完了レスポンスの url、video_url、または result_url から動画を取得します。

推奨する共通フィールドは次のとおりです。

用途推奨フィールド説明
モデルmodel現在のキーで /v1/models から取得した正確なモデル ID であること
テキストpromptテキストのみから動画を生成する場合は通常必須。空にできるかどうかはモデルによる
長さduration または secondsどちらか一方、単位は秒。duration を優先
アスペクト比ratio または aspect_ratio画面のアスペクト比の指定に推奨。使える値は対象モデルの機能による
参照画像images公開 HTTPS URL、またはアップロード済みの assets.88api.ai URL を推奨
参照動画metadata.referenceVideos対象モデルが対応している場合のみ使用
参照音声metadata.referenceAudios対象モデルが対応している場合のみ使用
開始・終了フレームmetadata.firstFrame、metadata.lastFrame対象モデルの開始・終了フレームのルールと、素材の併用制限に従うこと

上の表は多くのモデルに共通する書き方です。一部のブランドではフィールドが異なります(たとえば Wan の開始・終了フレームと参照素材は media 配列がおすすめで、読み取れない素材フィールドは 400 になります)。ブランド別の呼び出し仕様に従ってください。

size は一部のモデルと旧クライアントで使われる互換フィールドです。新しいクライアントでは ratio または aspect_ratio を優先し、対象モデルの機能説明に沿って具体的な値を選んでください。

このページの以降の例にある <MODEL_ID> は、上記の手順で /v1/models から取得した実際のモデル ID を表します。すべてのアカウントで同じ固定文字列になるわけではありません。

2. エンドポイント早見表

用途メソッドとパス説明
モデルの取得GET https://api.88api.ai/v1/models現在の API キーで参照できるモデル ID を返します。返された結果が正です
生成の作成POST https://api.88api.ai/v1/videosテキストと参照素材を送信し、タスク id を返します
タスクの照会GET https://api.88api.ai/v1/videos/{id}ステータス、進捗、エラーを照会します
素材アップロードの申請POST https://api.88api.ai/v1/media/uploadsファイルのダイジェスト、バイト数、MIME を送り、短期間有効なアップロード許可を取得します
素材バイナリのアップロードPUT {upload_url}返された専用のアップロードヘッダーを使い、API キーは送りません
動画の取得GET {url}完了レスポンスの結果 URL を優先して使い、パスを自分で組み立てません
旧コンテンツエンドポイントGET https://api.88api.ai/v1/videos/{id}/contentアーカイブ済み動画向けの互換リダイレクト。すべての結果に使える汎用のダウンロード方法ではありません

リクエストヘッダー

Authorization: Bearer sk-あなたのAPIキー
Content-Type: application/json
Accept: application/json

API キーは必ずサーバー側で保管し、ブラウザー、ミニプログラム、アプリのフロントエンドのバンドルに含めないでください。

操作認証
タスクの作成・照会、アップロード許可の申請Authorization: Bearer ...。api.88api.ai の API にだけ送信
ファイルのアップロードheaders 内の X-Media-Upload-Token と Content-Type をそのまま使用
公開メディアの読み取りassets.88api.ai の URL には Bearer、Cookie、ログインは不要

匿名で読み取れることは、匿名でアップロードできることを意味せず、タスクの詳細も公開されません。公開メディア URL を知っている人は、有効期限内であればファイルを読み取れます。URL を厳密なプライバシー保護の仕組みとして扱わないでください。メディア URL、公式の結果 URL、リダイレクト先に自分の API キーを転送しないでください。

まず現在のアカウントで使えるモデル ID を取得する

モデル ID はすべてのアカウントで同じとは限りません。クライアントの初回接続時や、モデル一覧を定期的に更新するときは、まず次を実行します。

curl 'https://api.88api.ai/v1/models' \
  --header 'Authorization: Bearer sk-xxxx'

レスポンスの data[].id からモデルを選び、その値をそのまま後続の POST /v1/videos の model フィールドに入れます。モデルの表示名から ID を組み立てたり、他のアカウントや古いドキュメントにあるモデル名が現在のアカウントでも必ず使えると考えたりしないでください。

{
  "object": "list",
  "data": [
    {
      "id": "<MODEL_ID>",
      "object": "model",
      "owned_by": "88api"
    }
  ]
}

3. 標準の作成リクエスト

最小構成のテキストから動画生成リクエスト

curl --request POST 'https://api.88api.ai/v1/videos' \
  --header 'Authorization: Bearer sk-xxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "<MODEL_ID>",
    "prompt": "雨の夜の街を走る銀色のスポーツカー、ローアングルの追従ショット、ネオンの映り込み、映画のような質感",
    "duration": 8,
    "ratio": "16:9"
  }'

duration は文字列形式の seconds でも指定できます。

{
  "model": "<MODEL_ID>",
  "prompt": "日の出の海岸を空撮、雲がゆっくり流れる",
  "seconds": "8",
  "ratio": "16:9"
}

共通リクエストフィールド

フィールド型必須説明
modelstringはい現在の API キーで GET /v1/models から取得した正確なモデル ID
promptstring条件付きテキストプロンプト。参照素材がある場合に空を許可するのは一部のモデルのみ
negative_promptstringいいえマルチ参照モデルのネガティブプロンプト。Veo では metadata.negativePrompt とも書けます
durationintegerいいえ動画の長さ(秒)。seconds とはどちらか一方
secondsstringいいえ文字列形式の動画の長さ。例:"8"
ratiostringいいえ推奨のアスペクト比フィールド。例:16:9、9:16
aspect_ratiostringいいえratio の互換エイリアス。使える値は対象モデルの機能による
sizestringいいえ互換フィールド。新規の接続ではアスペクト比の指定に使わないでください
resolutionstringいいえ対象モデルが対応している場合のみ使用。例:480p、720p、1080p、4k
imagestringいいえ参照画像 1 枚の URL
imagesstring[]いいえ参照画像 URL の配列。推奨の書き方
videostringいいえ参照動画 1 本の URL。Gemini Omni ではこのトップレベルフィールドが必須
videosstring[]いいえ参照動画の配列。その他のマルチ参照モデルは metadata.referenceVideos を使用
seedintegerいいえ乱数シード
generateAudio / generate_audiobooleanいいえ対応モデルで音声を同時に生成します。モデルの機能が許す場合のみ使用
metadataobjectいいえ参照動画、音声、開始・終了フレームなどの拡張フィールド

解像度の指定方法

作成 API は共通ですが、解像度の選び方はモデルによって異なる場合があります。まず GET /v1/models が返すモデル ID とモデルの機能説明を確認してください。

固定解像度モデル:モデル ID で解像度を選ぶ

一部のモデルは、モデル名またはモデル ID で出力解像度が固定されています。まず GET /v1/models から現在のアカウントで実際に使える ID を取得し、目的の解像度に対応するモデルを直接選んでください。

{
  "model": "<FIXED_RESOLUTION_MODEL_ID>",
  "prompt": "夜の街並みの中、車が通りをゆっくり走り抜ける",
  "duration": 8,
  "ratio": "16:9"
}

固定解像度モデルでは、resolution で出力解像度を一時的に変更することはできません。クライアントが resolution を付けて送っても、モデルの機能を上書きする手段として扱わないでください。

解像度選択可能なモデル:resolution フィールドを使う

複数の解像度に対応するモデルでは、リクエストに小文字の resolution を指定します。

{
  "model": "<MULTI_RESOLUTION_MODEL_ID>",
  "prompt": "夜の街並みの中、車が通りをゆっくり走り抜ける",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9"
}

実際に使える解像度と値は、引き続き現在の API キーの /v1/models、モデルの説明、サーバー側の検証結果が正です。複数のモデルに対応するクライアントでは resolution フィールドを残しておいてかまいません。このフィールドに対応するモデルは出力解像度の選択に使い、固定解像度のモデルは model に従います。quality、vquality を使ったり、モデル名を書き換えたりしてモデルの制限を回避しないでください。対応していない組み合わせには 400 が返されます。

4. 参照画像・動画・音声

3.1 参照画像

複数の画像は、トップレベルの images 配列にまとめて指定します。

{
  "model": "<MODEL_ID>",
  "prompt": "人物の顔立ち・服装・配色を一貫させ、海辺をゆっくり歩く。映画のような柔らかい光",
  "duration": 10,
  "ratio": "16:9",
  "images": [
    "https://cdn.example.com/character-front.jpg",
    "https://cdn.example.com/character-side.jpg"
  ]
}

画像 1 枚なら image や input_reference も使えますが、新規の接続では images 配列に統一することを推奨します。

3.2 参照動画

機能一覧で複数の参照動画に対応しているモデルでは、metadata.referenceVideos に指定します。

{
  "model": "<MODEL_ID>",
  "prompt": "参照のカメラワークとテンポを取り入れつつ、被写体の外観は変えない",
  "duration": 8,
  "ratio": "16:9",
  "images": ["https://cdn.example.com/subject.jpg"],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/camera-motion.mp4"
    ]
  }
}

3.3 参照音声

機能一覧で参照音声に対応しているモデルでは、metadata.referenceAudios に指定します。

{
  "model": "<MODEL_ID>",
  "prompt": "人物が参照音声のリズムに合わせて歌い、口の動きは自然に",
  "duration": 10,
  "ratio": "16:9",
  "images": ["https://cdn.example.com/singer.jpg"],
  "metadata": {
    "referenceAudios": [
      "https://cdn.example.com/voice-reference.mp3"
    ]
  }
}

minimax-h3 の参照画像にはトップレベルの images を使わないでください。MiniMax 動画 API 仕様に従い、metadata.referenceImages を使ってください。

3.4 マルチ参照モデルでの素材の組み合わせ

{
  "model": "<MODEL_ID>",
  "prompt": "参照画像の製品の外観、参照動画のカメラのテンポ、参照音声のサウンドの雰囲気を使ってテック系の広告を作る",
  "duration": 12,
  "ratio": "16:9",
  "images": [
    "https://cdn.example.com/product-front.jpg",
    "https://cdn.example.com/product-detail.jpg"
  ],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/motion-reference.mp4"
    ],
    "referenceAudios": [
      "https://cdn.example.com/sound-reference.mp3"
    ]
  }
}

同じ種類の素材に、複数のエイリアスフィールドを同時に使わないでください。たとえば、トップレベルの images と metadata.referenceImages を同時に送らないでください。複数の互換フィールドがある場合、サーバー側はそのうち 1 組だけを採用し、マージは保証しません。

3.5 素材 URL の要件

  1. 参照動画と参照音声には、匿名でダウンロードできる公開 HTTPS URL を使います。blob:、ローカルパス、data:video/... は汎用の参照動画プロトコルとしては使えません。ローカルファイルは次の節の手順で先にアップロードしてください。
  2. URL が Cookie、ブラウザーのログイン状態、Referer、独自のリクエストヘッダーに依存していないこと。
  3. localhost、プライベート IP、Docker のサービス名、自社の内部ネットワークからしかアクセスできないアドレスは使えません。
  4. URL はタスクの生成中ずっと有効である必要があります。有効期間は 60 分以上を推奨します。
  5. 画像は JPG、PNG、WebP、動画は MP4/MOV、音声は MP3/WAV を推奨します。
  6. 動画は 1 本あたり 50 MB 以下、音声は 1 本あたり 15 MB 以下を推奨します。大きすぎる素材は、ダウンロードや審査の段階で失敗することがあります。
  7. 第三者の素材を参照する前に、必要な著作権、肖像権、利用許諾を得ていることを確認してください。

素材のページが開けても、動画のバイト列をダウンロードできるとは限りません。HTML の共有ページではなく、実際のメディアを返す URL である必要があります。また、URL が使えても、エンコード、長さ、サイズが対象モデルの要件を満たしているとは限りません。Google の動画モデルでは画像に Base64 やファイルアップロードも使えます。詳しくは Google 動画 API 仕様を参照してください。参照動画は引き続き URL のみ受け付けます。

3.6 ローカル素材のアップロード:申請してから PUT

この API は一時的なメディアストレージを提供するもので、動画の生成、トランスコード、圧縮、フレームの自動抽出は行いません。

ステップ 1:サーバー側でアップロード許可を申請します。

POST https://api.88api.ai/v1/media/uploads
Authorization: Bearer sk-xxxx
Content-Type: application/json
{
  "size": 1234567,
  "mime_type": "video/mp4",
  "sha256": "<ファイルの生バイト列のSHA-256をパディングなしBase64URLでエンコードした値>"
}
フィールドルール
size元ファイルのバイト数。整数で 1–100,000,000。Base64 文字列の長さではありません
mime_type実際のファイル形式、およびアップロード時の Content-Type と一致させる
sha256SHA-256 の 32 バイトのダイジェストを Base64URL でエンコードし、= を付けない。64 文字の 16 進文字列ではありません

アップロードできる形式:video/mp4、video/webm、video/quicktime、audio/mpeg、audio/wav、audio/ogg、audio/mp4、audio/flac、image/png、image/jpeg、image/webp、image/gif。アップロードの上限はモデルの参照素材の上限とは別です。対象モデルのより厳しい制限も満たす必要があります。

HTTP 200 のレスポンス例(山かっこはプレースホルダーで、そのまま使える実際の値ではありません):

{
  "url": "https://assets.88api.ai/media/reference-media/<object-id>.mp4",
  "upload_url": "https://assets.88api.ai/media/reference-media/<object-id>.mp4",
  "method": "PUT",
  "headers": {
    "Content-Type": "video/mp4",
    "X-Media-Upload-Token": "<scoped-upload-token>"
  },
  "expires_at": 1789373400
}

ここでの expires_at は アップロード許可の有効期限(Unix 秒、約 10 分)で、ファイルの保存期限ではありません。この時点の url も、ファイルのアップロードが完了したことを意味しません。許可で書き込めるのは指定されたファイルだけで、バケット全体にはアクセスできません。

ステップ 2:許可の期限が切れる前に、元のバイナリをアップロードします。 レスポンスの upload_url、method、headers をそのまま使います。

# 以下の変数は許可申請のレスポンスから取得します。API_KEY をアップロード先に送らないでください。
curl --request PUT "$UPLOAD_URL" \
  --header 'Content-Type: video/mp4' \
  --header "X-Media-Upload-Token: $UPLOAD_TOKEN" \
  --data-binary @reference.mp4

multipart/form-data ではなく、-F も使いません。JSON の Base64 でもありません。申請時と同じ Content-Length、MIME、ファイルのバイト列を送る必要があります。ブラウザーでは File/Blob をそのまま送れば、Content-Length はブラウザーが付けます。サーバー側のストリーミングクライアントでも正しい長さを指定し、長さ不明の chunked アップロードは使わないでください。

HTTP 201 はアップロード完了を表し、url、size、mime_type、expires_at を返します。こちらの expires_at が素材の有効期限です(Unix 秒、そのオブジェクトのアップロードから 30 日)。成功を確認してから、url を対象モデルが求める参照フィールドに指定してください。ブラウザーアプリでは、自社のバックエンドで許可を申請してからブラウザーで直接アップロードし、長期間有効な API キーをフロントエンドに露出させないでください。

同じアップロード先は上書きできません。重複して PUT すると 409 が返るので、すでにアップロードに成功した URL を再利用してください。結果がはっきりしないネットワーク切断が起きた場合は、すぐに新しいオブジェクトを申請せず、まずその URL に匿名で HEAD リクエストを送って確認してください。アップロードや参照によって新しい生成タスクが作られることはありません。

5. 対応モデルの開始・終了フレームモード

開始フレームと終了フレームは、metadata.firstFrame と metadata.lastFrame に指定します。

次の例は、これらのフィールドに対応したマルチ参照モデル向けです。Veo と Gemini Omni も metadata.firstFrame と metadata.lastFrame を受け付けます。その他の書き方は Google 動画 API 仕様を参照してください。

{
  "model": "<MODEL_ID>",
  "prompt": "早朝の誰もいない広場から、夜に明かりが灯った同じ構図へなめらかに移り変わる",
  "duration": 10,
  "ratio": "16:9",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

ルール:

  • lastFrame は単独では使えず、必ず firstFrame と一緒に指定します。
  • 開始・終了フレームに対応するモデルの多くは、開始・終了フレームと通常の参照画像・動画・音声の併用を認めていません。
  • 機能一覧で「排他」と記載されているモデルでは、開始・終了フレームと通常の参照素材のどちらか一方を選んでください。

6. 現在の動画モデル機能一覧

以下の表は公開モデルの機能を説明するもので、表中の名前はリクエストに使う固定のモデル ID ではありません。実際のリクエストでは、現在の API キーで /v1/models が返す id を使ってください。アカウントによって表示されるモデル ID は異なる場合があります。

ブランド別の呼び出し仕様

パラメーターの書き方や素材のフィールドはブランドごとに異なります。接続前に該当するブランドのページを確認してください。

ブランドページモデル
Seedancedoubao-seedance-2.0、doubao-seedance-2.5、doubao-seedance-2.5-flash、doubao-seedance-2.0-fast、doubao-seedance-2.0-mini
Googleveo-3.1、veo-3.1-fast、gemini-omni-flash-1.1、gemini-omni-flash-1.2
MiniMaxminimax-h3
Wanwan3.0-video、wan3.0-video-prime
Grokgrok-imagine-video、grok-imagine-video-1.5

モデル機能一覧表

No.モデル機能/公開名長さアスペクト比出力画像/動画/音声の上限開始・終了フレーム音声の制御
1doubao-seedance-2.04–15 秒。-1 に対応16:9 4:3 1:1 3:4 9:16 21:9 adaptive480P/720P/1080P/4K、デフォルト 720P9 / 3 / 3対応、通常素材とは排他デフォルトで音声あり、オフ可
2doubao-seedance-2.54–30 秒。-1 に対応同上480P/720P/1080P、デフォルト 720P30 / 10 / 10対応、通常素材とは排他デフォルトで音声あり、オフ可
3doubao-seedance-2.5-flash4–30 秒。-1 に対応同上480P/720P、デフォルト 720P10 / 5 / 5対応、通常素材とは排他。開始フレーム使用時は比率が開始フレームの画像に従うデフォルトで音声あり、オフ可
4doubao-seedance-2.0-fast4–15 秒。-1 に対応同上480P/720P、デフォルト 720P9 / 3 / 3対応、通常素材とは排他デフォルトで音声あり、オフ可
5doubao-seedance-2.0-mini4–15 秒。-1 に対応同上480P/720P、デフォルト 720P9 / 3 / 3対応、通常素材とは排他デフォルトで音声あり、オフ可
6veo-3.14/6/8 秒。参照画像使用時は 8 秒固定、延長は 1 回につき 7 秒追加16:9 9:16720P/1080P/4K3 / 0 / 0開始フレーム、開始・終了フレーム、参照画像に対応ネイティブ音声、generate_audio でオフ可
7veo-3.1-fast8 秒固定で出力16:9 9:16720P 固定で出力3 / 0 / 0開始フレーム、開始・終了フレーム、参照画像に対応常に音声あり
8gemini-omni-flash-1.13–10 秒、デフォルト 3 秒16:9 9:16720P/1080P/4K10 / 3 / 0開始フレーム、開始・終了フレームに対応非対応
9gemini-omni-flash-1.23–15 秒、デフォルト 3 秒16:9 9:16720P/1080P/4K10 / 3 / 0開始フレーム、開始・終了フレームに対応非対応
10minimax-h34–15 秒、デフォルト 5 秒16:9(デフォルト) 9:16 1:1 4:3 3:4 21:9。1080P/2K は 16:9 9:16 のみ768P/1080P/2K(超解像)、デフォルト 768P9(1080P/2K は 6)/ – / 3768P のみ、通常素材とは排他完成動画に音声トラックが付く、設定不可
11wan3.0-video2–30 秒、デフォルト 5 秒。-1 に対応adaptive(デフォルト) 16:9 9:16 1:1 4:3 3:4 21:9480P/720P/1080P、デフォルト 1080P10 / 5 / 5(media 配列を使用)対応、通常素材とは排他設定不可
12wan3.0-video-prime同上同上同上同上同上設定不可
13grok-imagine-video1–15 秒、デフォルト 8 秒。参照画像を使う場合は最長 10 秒16:9 9:16 1:1 4:3 3:4 3:2 2:3(aspect_ratio で指定)480P/720P14 / 0 / 0先頭フレームのみ。参照画像とはどちらか一方非対応
14grok-imagine-video-1.51–15 秒、デフォルト 8 秒同上480P/720P/1080P。末尾フレーム、キーフレーム、参照画像、参照ボイスを使う場合は最大 720P14(先頭・末尾フレームとキーフレームは別枠)/ 0 / 0先頭・末尾フレームと最大 4 個のキーフレームに対応。参照画像と併用可非対応

表の番号は 1 から始まり、読みやすさのためだけのもので、リクエストパラメーターではありません。表中の公開名や機能シリーズも対照用です。実際の呼び出しでは、現在の API キーで /v1/models が返す正確な id を使い、名前を組み立てたりしないでください。

モデル固有のルール

ブランドごとのフィールドの違いは大きく、特に間違えやすい点は次のとおりです。完全なルールは上記の各ブランドページを参照してください。

  • Wan の wan3.0-video* は開始フレーム・終了フレーム・参照素材を media 配列で送るのがおすすめです。metadata.firstFrame/lastFrame/referenceImages/referenceVideos/referenceAudios(スネークケースも可)、トップレベルの firstFrame/first_frame/lastFrame/last_frame、トップレベルの images(1 枚目が開始、2 枚目が終了フレーム、最大 2 枚)も media に変換されます。読み取れない素材フィールドは 400 になります。
  • Grok の aspect_ratio と ratio は同じ意味です。複数のアスペクト比フィールドを指定する場合は値を一致させてください。先頭フレームは 1 枚までです。末尾フレームは last_frame、キーフレームは keyframes、参照画像は reference_images で指定し、grok-imagine-video-1.5 では reference_audios でプリセットボイスを最大 3 個選べます。詳しくは Grok 動画 API 仕様を参照してください。
  • minimax-h3 の参照画像は metadata.referenceImages、開始・終了フレームは metadata.firstFrame/lastFrame を使います。トップレベルの images は用途が固定されないため、metadata.referenceImages / metadata.firstFrame で明確に指定してください。480P と 4K は提供を終了しました。
  • Veo と Gemini Omni の参照動画はトップレベルの video/videos を使い、metadata.referenceVideos は使いません。gemini-omni-flash は提供を終了しました。Gemini Omni と veo-3.1-fast は動画延長に対応しておらず、veo-3.1-fast は 720P、8 秒、音声付きで固定出力されます。
  • Seedance(doubao-seedance-2.0、doubao-seedance-2.5、doubao-seedance-2.5-flash、doubao-seedance-2.0-fast、doubao-seedance-2.0-mini)は実際のトークン数で課金されます。参照素材は images、videos、audios、firstFrame/lastFrame などのフィールドで指定でき、火山引擎 Ark の content 配列も使えます。トップレベルと metadata のどちらに置いてもかまいません。https:// の画像と動画の URL は自動的に素材ライブラリに保存されるため、実在の人物の写真や動画を参照に使えます。完成動画は Ark のリンクで、24 時間後に無効になります。送信後のタスクはキャンセルできません。詳しくは Seedance 動画 API 仕様を参照してください。
  • seedance-2.0、seedance-2.5、seedance-2.0-mini、seedance-2.0-fast(秒単位課金)は 2026-11-12 に提供を終了しました。それ以前の SD2.0、SD2.5 と「官方版」接尾辞付きの Seedance モデル名も提供を終了しています。doubao- 接頭辞が付いた同名のモデルに切り替えてください。

7. 作成レスポンス

作成に成功すると、すぐに公開タスク ID が返されます。

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "queued",
  "progress": 0,
  "created_at": 1788249600
}

id を保存してください。標準 API では task_id が返ることは保証されないため、新規の接続では必ず id を使ってください。

HTTP 200 は「タスクを受け付けた」ことを表し、動画の生成が完了したことを意味しません。

8. タスクのポーリング

curl 'https://api.88api.ai/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Authorization: Bearer sk-xxxx'

共通ステータス

status意味クライアントの対応
queued受付済み、待機中そのまま待つ
in_progress生成中そのまま待つ
completed完了返された url を読み取り、再生・ダウンロード・再利用する
failed失敗error.code と error.message を確認する
unknown不明な状態少し待って再試行し、続く場合はサポートに連絡する

完了レスポンスの例:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "completed",
  "progress": 100,
  "created_at": 1788249600,
  "completed_at": 1788250200,
  "url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
  "video_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
  "result_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4"
}

失敗レスポンスの例:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "video_generation_failed",
    "message": "動画の生成に失敗しました"
  }
}

ポーリング戦略

  1. 作成後 3–5 秒待ってから最初の照会を行います。
  2. 照会は 10–15 秒ごとを推奨します。毎秒のポーリングは避けてください。
  3. 対話型のクライアントでは 15 分を待機の目安にできます。サーバー側ではタスク ID を永続化して照会を続けられます。クライアントが待機をやめても、タスクの失敗、キャンセル、返金にはなりません。
  4. queued または in_progress の間に同じタスクを再送信しないでください。重複課金の原因になります。

1 回の HTTP リクエストのタイムアウト、クライアントの総待機時間、サーバー側のタスク期限はそれぞれ別の概念です。progress=100 だけで成功と判断せず、status を基準にしてください。ページやネットワークが復旧したら、元のタスクの照会を続けられます。

9. 動画ファイルの取得

タスクが completed になったら、照会で返された url を優先して使います。互換クライアントは video_url/result_url をフォールバックとして読み取れます。これらはサーバー側が提供する結果です。タスク ID や内部 ID からメディアのパスを組み立てないでください。

# RESULT_URL は完了レスポンスの値をそのまま使い、メディアサーバーに API キーを送らないでください。
curl --fail --location "$RESULT_URL" --output result.mp4

補足:

  • クライアントは HTTP 3xx のリダイレクトを許可する必要があります。curl では --location を付けてください。
  • 結果 URL は https://assets.88api.ai/media/... の場合もあれば、モデルプラットフォームの元の URL の場合もあります。そのまま使用し、パラメーターの削除・変更やドメインの置き換えをしないでください。assets の URL に独自のクエリパラメーターを追加しないでください(400 が返されます)。
  • 旧 /v1/videos/{id}/content は、アーカイブ済みの動画に 307 の互換リダイレクトを提供します。旧クライアントとの互換性のためだけのもので、結果を取得する固定の入口として使わないでください。404 が返った場合はタスクを照会し直して実際の結果 URL を取得し、むやみに再生成しないでください。
  • それ以外のタスク ID を組み立てたり、保存したり、依存したりしないでください。作成レスポンスで返された公開 id だけを使ってください。
  • 成果物を長期保存したい場合は、完了後に自社のオブジェクトストレージへダウンロードしてください。

9.1 保存・再生とモデル間での再利用

  • 本サービスでアップロードした素材とアーカイブした動画は、それぞれのオブジェクトのアップロードから 30 日間保存されます。繰り返しの読み取り、古いタスクの照会、繰り返しの参照によって期限が延長されることはなく、新たにコピーがアップロードされることもありません。モデルプラットフォームの直接リンクの有効期限はプラットフォームに従い、30 日より短い場合があるため(例:Seedance の完成動画は 24 時間のみ)、早めにダウンロードしてください。
  • 署名パラメーターがなくログインも不要だからといって、永続的に保存されるわけではありません。期限切れのファイルには 410 が返され、ライフサイクルによって削除された後は 404 になる場合があります。タスクの記録が残っていても、バイナリファイルが残っているとは限りません。
  • 公開メディアは GET、HEAD、単一範囲の Range、ブラウザーからのクロスオリジン読み取りに対応しています。X-Media-Expires-At(Unix 秒)を読み取れます。Range が成功すると通常は 206 が返ります。キャッシュによって元の有効期限が延びることはなく、どの地域でも同じダウンロード速度になるとは限りません。
  • Veo で生成した結果は、動画参照に対応した他のモデルの入力として使えます。ただし、URL がまだ有効で、形式・サイズ・長さが対象モデルの要件を満たしている必要があります。結果 URL をそのモデルの参照フィールドに直接指定すればよく、いったんダウンロードして再アップロードする必要はありません。veo-3.1 が入力動画を受け付けるのは動画の延長時だけで、veo-3.1-fast は入力動画を受け付けません。どちらも参照動画には対応していません。
{
  "model": "<MODEL_ID>",
  "prompt": "参照動画の被写体と動きを保ったまま、ショットを続ける",
  "duration": 4,
  "ratio": "16:9",
  "metadata": {
    "referenceVideos": ["<前のタスクが返した完全なHTTPS結果URL>"]
  }
}

10. JavaScript による完全なポーリング例

Node.js 22 以降が必要です。サーバー側で API_KEY、MODEL_ID、REFERENCE_FILE(MP4 ファイルのパス)を設定してください。MODEL_ID は現在の API キーの GET /v1/models レスポンスから取得します。TASK_ID を設定すると、再アップロードや再生成をせずに既存のタスクを再開できます。この例は有料の生成を 1 回作成し、最後に次の生成のリクエストボディを表示するだけで、2 回目の生成は自動では行いません。読みやすさのためファイルをメモリーに読み込んでいるので、大きなファイルを一括処理する場合は並列数を制限してください。

// video-api-example.mjs — Node.js 22+, run with API_KEY, MODEL_ID, and REFERENCE_FILE.
import { readFile, stat } from "node:fs/promises";
import { createHash } from "node:crypto";

const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY on your server");
const baseUrl = "https://api.88api.ai";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function apiJSON(path, body) {
  // No automatic POST retry: a timed-out create may already have been accepted.
  const response = await fetch(baseUrl + path, {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(120000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}

async function uploadMedia(file, mimeType) {
  const info = await stat(file);
  if (!info.isFile() || info.size < 1 || info.size > 100000000) {
    throw new Error("File must contain 1–100000000 bytes");
  }
  const bytes = await readFile(file);
  const permit = await apiJSON("/v1/media/uploads", {
    size: bytes.length, mime_type: mimeType,
    sha256: createHash("sha256").update(bytes).digest("base64url"),
  });
  const target = new URL(permit.upload_url);
  if (target.origin !== "https://assets.88api.ai" || permit.method !== "PUT") {
    throw new Error("Unexpected upload destination; do not send credentials");
  }
  const response = await fetch(target, {
    method: "PUT", headers: permit.headers, body: bytes,
    redirect: "error", signal: AbortSignal.timeout(120000),
  });
  // A 409/ambiguous upload is not automatically retried; HEAD permit.url first.
  if (response.status !== 201) throw new Error(`Upload HTTP ${response.status}`);
  return response.json();
}

async function waitForVideo(id, budgetMs = 15 * 60 * 1000) {
  const deadline = Date.now() + budgetMs;
  let delay = 4000;
  while (Date.now() < deadline) {
    await sleep(Math.min(delay, deadline - Date.now()));
    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    let response, state;
    try {
      response = await fetch(`${baseUrl}/v1/videos/${encodeURIComponent(id)}`, {
        headers: { Authorization: `Bearer ${apiKey}` },
        signal: AbortSignal.timeout(Math.min(30000, remaining)),
      });
      if (response.ok) state = await response.json();
    } catch {
      delay = Math.min(delay * 2, 60000);
      continue; // Retry a read, never create a replacement task.
    }
    if (response.status === 429 || response.status >= 500) {
      const retryAfter = response.headers.get("Retry-After");
      const seconds = retryAfter && /^\d+$/.test(retryAfter)
        ? Number(retryAfter)
        : (Date.parse(retryAfter || "") - Date.now()) / 1000;
      delay = Number.isFinite(seconds) && seconds > 0
        ? Math.max(1000, seconds * 1000)
        : Math.min(delay * 2, 60000);
      await response.body?.cancel();
      continue;
    }
    if (!response.ok) throw new Error(`Task ${id}: HTTP ${response.status}`);
    if (state.status === "completed") {
      const result = state.url || state.video_url || state.result_url;
      if (typeof result !== "string" || new URL(result).protocol !== "https:") {
        throw new Error(`Task ${id} completed without a usable HTTPS result URL`);
      }
      return result; // Keep official URLs and capability query parameters intact.
    }
    if (state.status === "failed") {
      throw new Error(`Task ${id}: ${state.error?.message || "video generation failed"}`);
    }
    if (!["queued", "in_progress", "unknown"].includes(state.status)) {
      throw new Error(`Task ${id}: unexpected status ${state.status}`);
    }
    delay = 12000;
  }
  throw new Error(`Stopped waiting for ${id}; save this ID and query later. Not cancelled.`);
}

async function main() {
  // Resume a saved task without uploading or creating another paid task.
  let id = process.env.TASK_ID;
  if (!id) {
    if (!process.env.MODEL_ID) throw new Error("Set MODEL_ID from GET /v1/models");
    if (!process.env.REFERENCE_FILE) throw new Error("Set REFERENCE_FILE");
    const media = await uploadMedia(process.env.REFERENCE_FILE, "video/mp4");
    const task = await apiJSON("/v1/videos", {
      model: process.env.MODEL_ID, prompt: "参照動画の被写体と動きを保ったまま、ショットを続ける",
      duration: 4, ratio: "16:9", metadata: { referenceVideos: [media.url] },
    });
    id = task.id;
    if (!id) throw new Error("Create response did not contain a task ID; do not blindly retry");
    console.log("Save task ID:", id); // Persist to your database in production.
  }
  const resultURL = await waitForVideo(id);
  console.log("Result URL:", resultURL); // This grants media access; do not log publicly.
  // This only shows the NEXT request body; it does not create a second paid task.
  console.log(JSON.stringify({
    model: process.env.MODEL_ID, prompt: "参照動画の被写体と動きを保ったまま、ショットを続ける",
    duration: 4, ratio: "16:9", metadata: { referenceVideos: [resultURL] },
  }, null, 2));
}

await main();

11. エラー処理と再試行

状況対処
HTTP 400モデル名、長さ、アスペクト比、素材の数、フィールドの位置を確認する
HTTP 401API キーがない、誤っている、または無効になっている
HTTP 403現在のキーにモデルまたはグループの権限がない
HTTP 404タスクが存在しない、現在のアカウントのものではない、または成果物がまだ準備できていない
アップロード HTTP 409指定したオブジェクトがすでに存在し、上書きできない。HEAD で確認し、成功済みの URL を再利用する
メディア HTTP 410ファイルの有効期限切れ。読み取りや再参照では延長されず、削除後は 404 になることもある
アップロード HTTP 415ファイルのシグネチャが宣言した MIME と一致しない。拡張子を変えるだけで別の形式に見せかけることはできない
メディア HTTP 416Range がファイルの範囲外、または形式に対応していない。HEAD でサイズを確認し直す
HTTP 429リクエストが速すぎるか、利用枠の制限に達した。Retry-After に従うか、指数バックオフで再試行する
HTTP 5xx一時的なサービスエラー。照会リクエストはバックオフして再試行できる
status=failedHTTP の照会は成功したが、生成に失敗した。error.message を確認する
素材のダウンロード失敗URL がインターネットから到達可能で、期限切れでなく、ホットリンク防止や認証に依存していないことを確認する
unsupported_reference_mediaモデルがその参照素材の種類に対応していない。アップロードやドメインの変更では解決しない
must be a public HTTPS URLローカルファイルは先にアップロードする。Blob、Data URL、HTTP、ログインが必要な URL は送信できない
input_download_failed自分の PC で開けるかどうかではなく、対象サービスへの実際の到達性、DNS/ネットワーク、メディアの有効期限を確認する
コンテンツの安全性チェックによるブロックプロンプトや参照素材を見直す。同じ内容で何度も再試行しない

POST /v1/videos は現在、独自の冪等キーには対応していません。完全なリクエストを送信した後にネットワークのタイムアウトが発生した場合は、すぐにやみくもに再送信しないでください。複数のタスクが生成され、それぞれ課金されるおそれがあります。