> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 動画とバッチのジョブ

> 非同期ジョブを追跡し、Webhookを受信し、プロバイダー固有の動画オプションを渡します。

<Note>
  Video APIとBatch APIは、選ばれたワークスペース向けの招待制ベータプレビューです。利用可能かどうかは**設定 → 機能プレビュー**で確認してください。アクセスはワークスペース単位で管理され、個人のWeb設定を有効にしてもAPIアクセスは許可されません。通常のモデル利用料金がかかります。
</Note>

動画生成とバッチ処理は、作業が完了する前にジョブを返します。その`id`を保存し、返された`polling_url`で最新の状態を取得してください。作成応答が成功しても、生成やバッチ処理が完了したとは限りません。

ベータ期間中は、小さなリクエストとAPIキーの支出上限から始めてください。プロバイダーとモデルの機能は異なり、参照入力、キャンセル、出力の保持期間は選択したプロバイダーに依存します。完了した出力は期限切れになる前に自分でコピーを保存してください。

## 更新を受信する

どちらの種類のジョブを作成する場合も、自分のワークスペースに属するWebhookエンドポイントを指定します。

```json theme={null}
{
  "webhook": {
    "endpoint_id": "YOUR_ENDPOINT_ID",
    "events": ["job.status_changed", "job.completed", "job.failed", "job.cancelled", "job.expired"]
  }
}
```

Phaseoはプロバイダーの状態を照合し、顧客に通知します。Anthropicのメッセージバッチなど、ポーリングが必要なプロバイダーでも顧客向けWebhookを生成できます。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`を使います。

```json theme={null}
{
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": { "url": "https://example.com/start.png" }
    }
  ],
  "input_references": [
    {
      "type": "image_url",
      "role": "reference",
      "image_url": { "url": "https://example.com/character.png" }
    }
  ]
}
```

参照URLはHTTPSを使う必要があります。参照専用画像では`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の下に指定します。

```json theme={null}
{
  "provider_options": {
    "atlascloud": { "watermark": false, "output_format": "mp4" },
    "byteplus": { "camera_fixed": true }
  }
}
```

選択されたプロバイダーのオプションだけが転送されます。オプションではプロバイダーを選べません。選択には`provider`のルーティング設定を使ってください。`provider_options`を従来の`provider_params`と組み合わせないでください。ネストされたオプションは、ゲートウェイが管理する請求やコールバックのフィールドを上書きできません。

| プロバイダー | ネイティブ拡張の例 | 参照 |
| - | - | - |
| AtlasCloud Seedance 2.5 | `watermark`, `output_format`, `return_last_frame`, `omni_reference_task_type` | [モデルAPI](https://www.atlascloud.ai/models/bytedance/seedance-2.5/reference-to-video) |
| Novita Seedance 1.5 | `watermark`, `camera_fixed`, `fps` (24), `service_tier` (`default`) | [統合動画API](https://docs.novita.ai/api-reference/reference-unified-video-generation) |
| BytePlus Seedance | `camera_fixed` | 使用前に、選択したモデルのプロバイダー仕様を確認してください。 |
| MiniMax V1 | `fast_pretreatment`。プロンプト最適化には標準の`enhance_prompt`を使います | [動画API](https://platform.minimax.io/docs/api-reference/video-generation-t2v) |

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の仕様](https://platform.minimax.io/docs/api-reference/video-generation-v2-create)を参照してください。

## バッチのプロバイダー

バッチリクエストも`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キーを使ってください。

```bash theme={null}
curl --fail "https://api.phaseo.app/v1/batches/$BATCH_ID/results" \
  -H "Authorization: Bearer $PHASEO_API_KEY" \
  --output results.jsonl
```

応答は、対応するすべてのバッチプロバイダーで同じエンドポイントからJSONLをストリーミングします。Phaseoは分離された成功・エラーファイルを結合し、インライン結果配列をJSONLに変換し、結果のページ送りを処理します。生成内容と各リクエストのエラーは保持されます。行フィールドはプロバイダー固有のままです。OpenAI互換およびAnthropicの行は`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`を返します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.