Video APIとBatch APIは、選ばれたワークスペース向けの招待制ベータプレビューです。利用可能かどうかは設定 → 機能プレビューで確認してください。アクセスはワークスペース単位で管理され、個人のWeb設定を有効にしてもAPIアクセスは許可されません。通常のモデル利用料金がかかります。
idを保存し、返されたpolling_urlで最新の状態を取得してください。作成応答が成功しても、生成やバッチ処理が完了したとは限りません。
ベータ期間中は、小さなリクエストとAPIキーの支出上限から始めてください。プロバイダーとモデルの機能は異なり、参照入力、キャンセル、出力の保持期間は選択したプロバイダーに依存します。完了した出力は期限切れになる前に自分でコピーを保存してください。
更新を受信する
どちらの種類のジョブを作成する場合も、自分のワークスペースに属するWebhookエンドポイントを指定します。batch.completedやvideo.failedなどの名前空間付きイベント型を使ってください。汎用のjob.*イベント型も引き続き対応しており、両方のジョブ種別で該当する段階を購読します。
エンドポイントのシークレットでx-phaseo-signatureを検証します。署名は、x-phaseo-timestamp、文字どおりのピリオド、変更していないリクエスト本文を連結したデータの、16進表記HMAC-SHA256です。タイムスタンプの鮮度を確認し、x-phaseo-event-idで重複を除き、受け付けた配信には成功のHTTP応答を返してください。配信は再試行されたり順不同で届いたりする場合があります。矛盾する状態変更を適用する前にジョブを取得してください。
エンドポイントを保存したら、設定のテストイベントを送信で署名付きのwebhook.testペイロードを配信できます。テスト配信は1回だけ試行し、再試行もジョブ配信履歴への追加も行いません。
ライフサイクルの状態completed、failed、cancelled、expiredは最終状態として扱います。Webhookを使う場合も、ポーリングによる復旧手段を残してください。
Phaseoは各イベントについて最初の配信を1回試行します。成功の2xx応答で配信は終了し、再試行は不要です。失敗した配信は最大3回、1分、5分、15分後に再試行されます。バックグラウンドの定期処理が対象の再試行を実行するため、実際の配信は予定時刻より遅れる場合があります。各試行には番号、時刻、HTTPステータス、エラー、次の再試行時刻が記録されます。4回目の失敗後、配信は恒久的な失敗になります。受信側での重複排除は引き続き必要です。確認応答の消失やWorkerの中断で、配信結果が不確実になる場合があります。
ジョブとリクエストのログを見る
設定 → 使用量 → ログで、推論リクエストの詳細はリクエスト、動画のライフサイクルは動画、バッチジョブと行ごとの結果はバッチを使います。動画とバッチの詳細には、請求状態、プロバイダー試行、Webhook試行が含まれます。ジョブが成功してもWebhook配信が失敗することがあります。 動画の送信では、プロバイダーに接続する前にクレジットを予約します。タスクIDがないタイムアウトでは照合のため予約を維持します。これは生成失敗の証拠ではありません。有料の動画またはバッチ予約が、処理成功後に予期せずゼロ価格になると、調査のためunexpected_zero_costで請求を未完了のままにします。作成応答のコストがゼロであること自体は、非同期生成では正常です。
動画の入力
動画料金を理解する
動画料金はプロバイダーとモデルに依存します。秒単価には課金対象の長さを掛ける必要があり、クリップ単価は指定された長さと解像度にのみ適用されます。複数の出力や課金対象の参照入力で合計が増える場合があります。 LTXのテキスト／画像生成は出力秒数を、音声から動画への生成は入力音声秒数を課金します。BytePlus Seedanceは動画トークンを使い、参照動画がある場合は料金が異なります。MiniMax Hailuo V1は固定長クリップ料金を使い、H3は秒数を使って参照入力にも課金する場合があります。表示された単価をリクエスト全体の費用と解釈せず、選択したプロバイダーの料金計算要素を確認してください。 予約は送信前に保持される見積額です。最終請求はジョブの課金対象使用量に基づき、未使用の予約クレジットは照合後に解放されます。プロバイダーが対応する解像度やオプションでも、ベータで利用できるとは限りません。 出力の長さにはsecondsまたはdurationを使います。両方を指定した場合は一致する必要があります。resolutionとaspect_ratio、または1280x720のようなピクセル単位のsizeを使ってください。
最初と最後のフレームを明示するにはframe_imagesを使います。
role: "reference"を明示してください。frame_imagesのない従来のリクエストは、ラベルのない最初の画像を最初のフレームとして扱います。frame_imagesを、input_referencesの最初／最後のフレームの役割やinput_referenceと組み合わせないでください。
動画と音声の参照はtype: "video_url"または"audio_url"とmedia_url: { "url": "https://..." }を使います。対応する組み合わせはモデルとプロバイダーによって異なります。参照の長さが料金に影響する場合は、input_video_durationとinput_audio_durationを秒単位で指定してください。
プロバイダーのオプション
モデル、長さ、解像度、音声生成、入力メディア、出力数は標準フィールドに設定します。プロバイダー固有の拡張は、正式なプロバイダーIDの下に指定します。providerのルーティング設定を使ってください。provider_optionsを従来のprovider_paramsと組み合わせないでください。ネストされたオプションは、ゲートウェイが管理する請求やコールバックのフィールドを上書きできません。
AtlasCloud Seedanceはネイティブの
resolution、ratio、last_imageフィールドを使います。参照から動画を生成する版は、順序付きの画像、動画、音声参照を受け取ります。自動長編集（duration: -1）は、ゲートウェイの固定長予約仕様では対応していません。モデルをルーティングする前に、プロバイダーのモデル利用可否と料金を設定する必要があります。プロバイダーオプションでは、利用できないモデルを有効にできません。
MiniMax H3はV2を使い、768Pまたは2Kで整数の4〜15秒に対応します。H3 Maxは480Pまたは768Pで整数の5〜15秒に対応し、テキストまたはフレーム画像を使えます。H3は画像、動画、音声の参照に対応しますが、参照を最初／最後のフレームと混在させることはできません。両モデルとも1リクエストにつき1動画を生成し、V1のプロンプト最適化オプションには対応しません。標準のaspect_ratioを使ってください。フレーム入力は自身の比率で決まります。参照動画の予約はプロバイダーの15秒入力上限をカバーし、実使用量は完了時に精算されます。MiniMax V2の仕様を参照してください。
バッチのプロバイダー
バッチリクエストもprovider_optionsを受け付けます。OpenAIはoutput_expires_after、Mistralはmetadataに対応します。正式なプロバイダーIDを使い、これらのフィールドをトップレベルに重複指定しないでください。例えばprovider_options: { "openai": { "output_expires_after": { "anchor": "created_at", "seconds": 86400 } } }はOpenAI出力の保持期間を設定します。行の入力、モデル、エンドポイント、Webhook送信先はオプションで上書きできません。
Mistralにはすでにネイティブのバッチアダプターがあります。Anthropicのメッセージバッチはポーリングされ、他のプロバイダーではポーリングとネイティブの完了通知を組み合わせる場合があります。利用可否は、プロバイダーの対応エンドポイントとデプロイのバッチ許可リストに依存します。ファイルやインラインリクエストを送信する前に、バッチ機能の応答を確認してください。
完了したバッチにも失敗行が含まれる場合があります。すべての行が成功したと仮定せず、カスタムIDで各結果を確認してください。結果と請求の照合が終わるまで、元の入力とジョブIDを保存します。プロバイダーが元のリクエストを受け付けている可能性があるため、送信結果が不確かな場合は再送前に調査してください。
バッチ結果をダウンロードする
対応するバッチが最終状態になると、そのresults_urlは認証付きのPhaseoダウンロードを指します。バッチを所有するワークスペースの通常のPhaseo APIキーを使ってください。
custom_id、Geminiはリクエストメタデータ、xAIはbatch_request_idを使ってください。Anthropicの成功行にはresult.messageに生成メッセージが含まれます。
ダウンロードはOpenAI、Anthropic、Google AI Studio、Mistral、Together、Groq、Alibaba Cloud、Moonshot、Parasail、OVHcloud、xAIのアダプターに対応します。プロバイダーの利用可否は引き続きプレビューアクセスと送信許可リストに依存し、ダウンロード対応によって追加のルートは有効になりません。既存のoutput_file_id、error_file_id、ファイル内容エンドポイントも利用できます。バッチのリクエスト行エンドポイントに含まれるのは追跡と請求のメタデータで、生成メッセージ本文ではありません。
結果のダウンロードは、別のバッチを送信せず、推論料金を追加しません。プロバイダーの認証情報は不要です。Webhookはジョブ更新を通知するので、結果は別途ダウンロードしてください。最終状態のジョブでも、結果が一部のみ、または出力がない場合があります。エンドポイントは処理中に409、出力がない場合に404を返します。プロバイダーの保持期間が終了する前に結果を保存してください。ダウンロードが中断した場合は部分ファイルを破棄し、バッチ送信ではなくダウンロードを再試行します。インラインJSON結果は1行あたり8 MiBの安全上限付きでストリーミングされ、ネイティブJSONLファイルにはこの行上限がありません。
大きな出力では、TypeScriptのclient.batches.streamResults(batchId, { signal })がバッファリングなしでReadableStream<Uint8Array>を返します。保存先へ接続し、途中停止する場合はストリームをキャンセルするかシグナルを中断してください。ダウンロード全体に固定タイムアウトはありません。Pythonのclient.batches.stream_results(batch_id)は設定されたHTTPタイムアウトでバイトチャンクを生成し、途中停止する場合はイテレーターを閉じます。生成されたretrieveBatchResults操作はJSONLテキスト全体を返すため、小さな出力に適しています。
バッチダウンロードの制限
バッチ結果のダウンロードは、移動する30分間の窓でワークスペースおよびバッチごとに10回まで試行できます。APIキーおよび/batches、/batchの別名間で共有されます。ダウンロード受付に到達した試行は、上流ダウンロードが失敗またはキャンセルされても数えられます。所有権や準備状態の不備は数えられません。429応答には秒単位のRetry-Afterが含まれます。制限サービスが利用できない場合は、Retry-After: 30付きの503を返します。