申請プロセス
APIを使用するには、まず Sora Videos Generation API の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。
初回申請時には無料のクレジットが付与され、このAPIを無料で使用できます。
基本使用
まず、基本的な使用方法を理解します。これは、プロンプトprompt、参照画像リンクの配列 image_urls、およびモデル model を入力することで、処理された結果を得ることができます。具体的な内容は以下の通りです：
accept：受け取りたいレスポンス結果の形式。ここではapplication/json、すなわちJSON形式を記入します。authorization：APIを呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
model：生成する動画のモデル。主にsora-2、sora-2-proがあり、現在sora-2、sora-2-proはsize、durationパラメータを自由に選択できる動画を生成できます。sora-2-proは25秒の動画をサポートしますが、sora-2は10秒、15秒の動画のみをサポートします。size：今回の動画生成タスクの解像度。small、largeがあります。image_urls：アップロードする参照画像リンクまたはBase64エンコードされた配列。duration：今回の動画生成タスクの長さ。10秒、15秒、25秒があります。現在、sora-2-proのみが25秒をサポートしています。character_start/character_end：画面内のキャラクターの開始位置と終了位置（0-1）。主体の位置を制御するために使用します。orientation：画幅の方向。landscape、portrait、squareをサポートします。prompt：プロンプト。callback_url：結果をコールバックするURL。
success：この時点での動画生成タスクの状態。task_id：この時点での動画生成タスクID。trace_id：この時点での動画生成追跡ID。data：この時点での動画生成タスクの結果リスト。id：この時点での動画生成タスクの動画ID。video_url：この時点での動画生成タスクの動画リンク。state：この時点での動画生成タスクの状態。
data の動画リンクアドレスに基づいて生成されたSora動画を取得するだけです。
また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURLのコードは以下の通りです：
画像から動画タスク
画像から動画タスクを実行したい場合、まずパラメータimage_urlsに参照画像リンクを渡す必要があります。以下の内容を指定できます：
- image_urls：この画像から動画タスクで使用する参照画像リンクの配列。
キャラクター生成動画タスク
キャラクター生成動画タスクを希望する場合、まずパラメータcharacter_urlにキャラクターを作成するための動画リンクを渡す必要があります。動画には必ず実在の人間が映ってはいけません。そうしないと失敗します。以下の内容を指定できます：
- character_url：キャラクターを作成するための動画リンク。動画には必ず実在の人間が映ってはいけません。そうしないと失敗します。
非同期コールバック
Sora Videos Generation APIによって生成される時間は比較的長く、約1〜2分かかります。APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、追加のシステムリソースを消費します。そのため、このAPIは非同期コールバックのサポートも提供しています。 全体の流れは、クライアントがリクエストを開始する際に、追加でcallback_urlフィールドを指定します。クライアントがAPIリクエストを開始すると、APIはすぐに結果を返し、現在のタスクIDを示すtask_idフィールド情報を含みます。タスクが完了すると、生成された動画の結果がPOST JSON形式でクライアントが指定したcallback_urlに送信され、その中にもtask_idフィールドが含まれます。これにより、タスクの結果をIDで関連付けることができます。
以下の例を通じて、具体的にどのように操作するかを理解しましょう。
まず、WebhookコールバックはHTTPリクエストを受信できるサービスであり、開発者は自分が構築したHTTPサーバーのURLに置き換える必要があります。ここでは、デモのために公開されたWebhookサンプルサイトhttps://webhook.site/を使用します。このサイトを開くとWebhook URLが得られます。以下のように示されています：
このURLをコピーすれば、Webhookとして使用できます。ここでのサンプルはhttps://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daaです。
次に、フィールドcallback_urlを上記のWebhook URLに設定し、対応するパラメータを入力します。具体的な内容は以下のようになります：
https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daaで生成された曲の結果を観察できます。以下のように示されています：
内容は以下の通りです：
task_id フィールドが含まれており、他のフィールドは上記と似ています。このフィールドを使用することで、タスクの関連付けが可能です。
エラーハンドリング
APIを呼び出す際にエラーが発生した場合、APIは対応するエラーコードとメッセージを返します。例えば：400 token_mismatched：不正なリクエスト、パラメータが欠落または無効である可能性があります。400 api_not_implemented：不正なリクエスト、パラメータが欠落または無効である可能性があります。401 invalid_token：未承認、無効または欠落した認証トークン。429 too_many_requests：リクエストが多すぎます、レート制限を超えました。500 api_error：内部サーバーエラー、サーバーで何かがうまくいきませんでした。