GetVibeは、テキストモデルAPIに加えて、非同期ジョブAPIを通じたメディア生成を提供しています。メディアのリクエスト経路はOpenAIのチャット補完とは異なります。生成ジョブを送信し、ジョブIDを受け取り、そのステータスと結果を取得します。画像、動画、音声／ボイスモデルでは入力と課金単位が異なるため、すべてのモデルで同じリクエスト形式が使えると想定せず、メディアモデルカタログから選択してください。
モデルを見つけ、要件を確認する
メディアカタログと/v1/models?type=image,video,audioを使用して、アカウントで利用できるメディアタイプを確認してください。各モデルの正確なID、受け付ける入力、サポートされるオプション、出力形式、価格単位を確認します。画像モデルは出力設定に基づいて課金される場合があり、動画は長さや解像度によって変わる場合があります。ボイスモデルでは、テキスト長、再生時間、またはその他の文書化された単位に基づいて課金されることがあります。これらの価格を、すべてテキストトークンであるかのように比較しないでください。
gpt-image-2はカタログにある画像モデルの1つです。モデルページとメディアドキュメントには、サポートされるアスペクト比、解像度、生成／編集オプションが記載されています。動画モデルにはそれぞれ固有の入力があり、処理に時間がかかる場合があります。ボイス機能はモデルによって異なるため、UIで特定の操作を提供すると約束する前に、現在のメディア一覧を確認してください。
画像ジョブを送信する
キーはサーバー上で管理してください。以下は、テキストから画像を生成するリクエストにおける、文書化された非同期形式です。プロンプトはトップレベルのフィールドに指定し、生成オプションはopts内に指定します。
curl https://getvibeapi.com/api/media/generate \
-H "Authorization: Bearer $GETVIBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean editorial illustration of a developer desk, no text",
"opts": {"aspect_ratio":"16:9", "resolution":"1K", "mode":"text-to-image"}
}'返されたjobIdを、自分のユーザーおよびタスクのレコードとともに保存してください。このリクエストは生成を開始しますが、完成した画像本体をインラインで返すものではありません。
ポーリングまたはWebhookを受け取る
小規模な統合では、ジョブのエンドポイントを適度な間隔でポーリングし、ジョブが終端状態に達したら停止してください。状態には、submitting、processing、success、fail、expiredがあります。数ミリ秒ごとにポーリングしても、生成速度は上がらず、トラフィックが増えるだけです。本番のバッチ処理では、文書化されたWebhookを設定し、重複配信によって重複アセットが作成されないよう、コールバックをべき等にしてください。
curl "https://getvibeapi.com/api/media/jobs/$JOB_ID" \
-H "Authorization: Bearer $GETVIBE_API_KEY"成功したら、結果URLを取得し、長期保存が必要な場合は自分で管理するストレージにメディアをコピーしてください。失敗した場合は、サポート用にジョブIDを保持し、役立つエラーを表示します。すべての失敗をリトライしないでください。無効なオプションは再度失敗します。また、重複した生成によって追加料金が発生する可能性があります。
動画とボイスにはモデル固有の処理が必要です
動画では、送信前にモデルの再生時間、フレームサイズ、画像コンディショニングの要件、サポートされるオプションを確認してください。リモートソースURLを検証し、到達可能であることを確認します。レンダリングにはテキスト生成より時間がかかる場合があるため、ジョブの進捗を表示してください。インタラクティブなページを開いたままにするのではなく、バッチ処理には文書化されたWebhookフローを使用してください。
ボイスと音声では、音声生成と文字起こしまたは音声理解を区別してください。これらは入力と出力のモダリティが異なります。モデルカードに合わせてエンドポイントとペイロードを選択し、設定できる場合はテキストまたは再生時間の上限を設定し、返された音声をプレーヤーが受け付ける形式で保存してください。すべてのメディアモデルがボイスを生成できると約束しないでください。
予算と失敗時の動作
バッチ処理の前にメディアモデルの現在の価格を確認し、実際の課金単位で見積もってください。テキストモデルの価格は、画像や動画の生成価格の目安にはなりません。本番で予定している解像度、再生時間、またはボイス設定を正確に使用して、サンプルを1件実行してください。ジョブID、モデル、オプション、再生時間、終端状態、課金対象の使用量を記録します。高額な出力や顧客向けの出力には、バッチサイズの上限と手動レビューを設定してください。
プライバシーポリシーで許可されていない限り、プロンプトやメディアURLを一般的なログに記録しないでください。認証情報をマスキングし、アップロードサイズの上限を適用し、非公開の生成アセットを公開URLとして公開しないでください。編集では、結果をレビューするまで元のアセットを別途保持してください。
本番運用前のチェックリスト
- 正確なモデルID、モダリティ、入力要件を確認する。
- APIキーをサーバー上で管理する。
- 文書化されたトップレベルのプロンプトと、モデル固有のオプションを使用する。
- ジョブIDを保存し、ポーリング／Webhook処理をべき等にする。
- 失敗および期限切れ時の動作を定義する。
- モデルの実際の課金単位に基づいて予算を設定する。
- 永続化が必要な場合は、成功した出力をストレージにコピーする。
リリース前に、メディア生成、メディアWebhook、メディアモデルをお読みください。公開モデル一覧とサポートされるオプションは変更される可能性があるため、アカウントに関する基準は、これらのページとライブカタログです。
ソースアセットを安全に扱う
画像から画像への生成や、画像で条件付けする動画生成では、そのモデル向けに文書化されたアップロード方法またはURL方式を使用してください。ソースURLが生成サービスから公開到達可能であり、ログイン済みのブラウザセッションを必要としないことを確認します。長期間有効な署名付きURLを、ログにコピーされる可能性のあるプロンプトに埋め込まないでください。ユーザーのファイルを受け付ける前に、自分のアプリケーションでアップロードサイズとContent-Typeを確認してください。
ユーザーが提供した画像から生成する場合は、元のファイルを保持し、同意と保持に関する要件を追跡してください。生成結果には、認識可能なソースの詳細が含まれる場合があります。共有する前に、プロダクトのプライバシーおよびモデレーションルールを適用してください。
ジョブの状態を中心にUIを設計する
ジョブIDが返された後は送信済み状態を表示し、サービスが処理している間は処理中状態を表示し、成功、失敗、期限切れについて明確な終端状態を表示してください。ジョブが非同期で継続する場合、ユーザーが安全に移動できるようにし、その後、自分で保存したジョブレコードを検索して状態を復元します。送信コントロールを無効にするか、自分でべき等性ガードを使用して、ダブルクリックによる重複処理の送信を防いでください。
バッチでは、完了、失敗、保留中の件数を別々に表示してください。集約されたスピナーだけでは、長時間かかる動画ジョブが正常なのか停止しているのか分かりません。ポーリングのバックオフに上限を設け、バッチが大きくなったら文書化されたWebhook経路に切り替えてください。
保持計画に基づいて結果を保存する
メディアドキュメントに記載がない限り、返された結果URLを永続ストレージとして扱わないでください。長期的なアクセスが必要な場合は、成功した出力をストレージバケットにダウンロードし、新しいオブジェクトIDをデータベースに保存します。生成ファイルにはアクセス制御を適用し、ユーザーがプロジェクトを削除した場合の削除動作を定義してください。
モデルID、オプション、プロンプトのバージョン、ジョブID、結果オブジェクト、終端ステータス、課金対象の使用量を記録してください。これにより、機密性の高いプロンプト全文をログに記録したり、チーム全員にメディアURLを公開したりしなくても、後からのサポート問い合わせに回答できます。