AI動画APIの選び方：非同期ジョブ、Webhook、返金

AI動画APIを選ぶのは、画像APIを選ぶのとはわけが違います。動画のレンダリングにかかるのは秒単位ではなく分単位。つまり、あなたの1週間をどれだけ食うかを決めるのは、フレームの品質ではなく統合の形です。ジョブモデルを読み違えると、あとでキュー、リトライ、課金の突き合わせを書き直すことになります。ここでは、最初のリクエストを書く前に確認すべき7つのポイントを、eroqの実装を具体例として紹介します。

1. ブロッキング呼び出しではなく非同期ジョブ

動画の完成を待ち続けるブロッキングのHTTPリクエストは、便利そうな顔をした罠です。ロードバランサーにもサーバーレス基盤にもCDNにも、長いレンダリングよりはるかに短いリクエスト上限があります。そのためブロッキング型のAPIはテストでは動いても、本番では、レンダリングがいつもより長引いたまさにその瞬間に落ちます。

正しい形はジョブです。eroqでは、POST /v1/videos/generationsがすぐにジョブIDを返します。あとはGET /v1/videos/generations/{id}をポーリングするか、Webhookを待ちます。完全なリファレンスは/docs/videoにあります。

# 1. submit
curl -X POST https://eroq.ai/v1/videos/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-lite",
    "prompt": "A courier weaves a bicycle between stopped cars on a wet avenue at dusk, headlights smearing across the frame. Tracking shot, 35mm film, anamorphic lens, neon noir palette, dynamic tempo.",
    "seconds": 5,
    "aspect": "9:16"
  }'

# 2. poll (or skip this and use a webhook)
curl https://eroq.ai/v1/videos/generations/JOB_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"

他のベンダーで確認すべきこと：動画エンドポイントが本当に非同期かどうか、そしてプロセスの再起動後にジョブを回収できる一覧エンドポイントがあるかどうか。レンダリングの記録が、失ったレスポンスの中にしかないなら、そのレンダリングは失われます。

2. 実際に検証できるWebhook

始めのうちはポーリングで十分ですが、量が増えると無駄が大きくなります。Webhookは署名付きで届くべきで、その署名方式は一度は実装したことのあるものが理想です。

eroqはStripe形式の署名ヘッダー付きでvideo.generation.succeededとvideo.generation.failedを送信します。ペイロードに含まれるのはインラインのbase64ではなくCDNのURLです。これは重要なポイントで、数メガバイトもあるJSONボディは、いずれスタックのどこかを壊します。

どのベンダーにも聞くべき質問は3つです。ペイロードは署名されているか、署名対象にリプレイ防止のための有効期間が含まれているか、ボディに入っているのはURLかバイト列か。2026年9月時点の各社のドキュメントで答えを確認してください。

3. レンダリングが失敗したらどうなるか

本物のプラットフォームとラッパーを分けるのがこの基準で、料金ページにはまず書かれていません。次の3つを確認しましょう。

失敗は返金されるか？ eroqでは、失敗した生成は自動で返金されます。突き合わせるのは試行ではなく、成功だけです。

ポリシーによる拒否は課金されるか？ ブロックされたリクエストはcontent_blockedを返し、課金されることはありません。規模が大きくなると、拒否に課金するプラットフォームは、自社のフィルターの代金をあなたに払わせていることになります。

チェックは引き落としの前か後か？ プランに含まれないモデルは、クレジットが動く前に403 plan_requiredを返します。キャパシティが確保されていないエンジンも、同じく引き落とし前に503 model_unavailableを返します。別のエンジンへの暗黙のフォールバックもありません。特定のモデルを指定してそれが使えなければ、返ってくるのはエラーであって、予想外のレンダラーではありません。暗黙のフォールバックはこの分野で最悪の障害パターンです。出力は変わるのに、ログは変わらないのですから。

4. 課金単位

主流は2つです。秒単位の従量課金と、決まった長さごとにクリップ単位で定額のクレジット。定額のほうが予算を立てやすく、経理チームにも説明しやすい一方、秒単位は半端な長さに対して公平です。どちらも間違いではありませんが、顧客に価格を約束する前に、自分がどちらの方式なのかを把握しておく必要があります。

eroqは、エンジンごとに決まった長さを基準にクレジットを課金します。Seedance 1.0 Liteなら5秒で120クレジット、Motion Oneは60、Kling 2.5 Turboは170、Veo 3 Fastは固定の8秒で216。ラインナップ全体は/modelsで確認できます。エントリーパックでは1クレジットが約1セントです。クレジットに有効期限はなく、ワークスペースはシートとキーをまたいで共有のウォレットを1つ持ちます。だからこそ、別々の請求関係が山のように増えるのではなく、顧客ごとの会計はあなたの側で管理することになります。生成を再販するなら、従量コストを転嫁する仕組みはAI APIのクレジット料金設計で解説しています。

5. プランに応じて拡大するレート制限

eroqのキーごとの制限は、1分あたりチャット60リクエスト、画像20、動画と音声合成は6が基本で、これにプランごとの倍率がかかります。Creatorは×2、Studioは×4、Teamは×6、Agencyは×8。キーの数もプランとともに増えます。Hobbyは10個、Creatorは20個、Studioは50個、Teamは100個、Agencyは200個です。例外はシートで、個人向けプランはどれも2シートが上限です。本格的なチームならTeam（25シート）かAgency（50）に移ります。

実践的なアドバイスとしては、環境ごとに1つ、顧客向けのサーフェスごとに1つキーを発行することです。そうすれば、ステージングで暴走したループが制限するのはステージングだけで済みます。どのベンダーでも、制限がキーごとなのかアカウントごとなのかを確認してください。この2つでは、影響範囲がまったく違ってきます。

6. ラインナップをハードコードしないためのディスカバリー

ラインナップは変わります。エンジンIDや価格をアプリにハードコードすれば、古いメニューを出荷することになります。

GET /v1/enginesは、各エンジンを必要なプラン、利用可否、機能（シード、終了フレーム、ネガティブプロンプト、音声に対応しているか）とともに返し、GET /v1/modelsは価格付きの全モデル一覧を返します。この2つのレスポンスからUIを組み立てれば、新しいエンジンは自動的に表示されます。仕様は/openapi.jsonで機械可読な形で公開されており、コーディングエージェント向けの/llms.txtもあります。

7. エージェント向けの窓口：MCPとCLI

動画APIを呼び出すのは、あなたのアプリではなくエージェントであることが増えています。用意しておきたい窓口は2つです。

リモートMCPサーバー。 eroqのサーバーはhttps://eroq.ai/mcpにあり、Streamable HTTPで動作し、同じBearerキーで認証します。公開しているツールはgenerate_image、generate_video、get_video_status、generate_speech、enhance_prompt、list_models、list_voices、list_characters、get_accountです。ChatGPTにはカスタムコネクタとして、Claudeにはウェブ版とデスクトップ版から、さらにCursorとCodex CLIにも接続できます。ヘッダーを送信できないクライアント向けには/mcp/<key>形式があります。この場合はURL自体が秘密情報になるので、そのつもりで扱ってください。クライアントごとの設定は/docs/mcpにあります。

claude mcp add --transport http eroq https://eroq.ai/mcp \
  --header "Authorization: Bearer $EROQ_API_KEY"

CLI。 eroqパッケージは依存関係ゼロで、Node 18以上で動作します。eroq login、eroq image "…"、eroq video "…" -s 8 --aspect 9:16、eroq speech "…" -v aria。eroq mcpは、メディアをファイルに書き出すローカルのstdio MCPサーバーを起動します。これこそ、コーディングエージェントが本当に求めている形です。

基本を押さえたら、さらに2つ

バッチの構造。 単発ではなく連続したシーンをレンダリングするなら、シーケンスそのものをモデル化したリソースを探しましょう。eroqのfilmsリソースは絵コンテを保存し、POST /v1/films/{id}/renderはすべてのシーンを撮影します。課金はシーンごとで、ウォレットの残高が尽きればきれいに停止します。詳しくは/docs/filmsをご覧ください。

出力のホスティング。 レンダリング結果のURLは恒久的なストレージではありません。成功時のWebhookで自分のバケットにコピーするか、/v1/storage/objectsのeroq Store（10 MBあたり2クレジット）を使って、記録の置き場を1つにまとめましょう。

チェックリスト

1. 回収用の一覧エンドポイントを備えた非同期ジョブ。
2. バイト列ではなくURLを運ぶ、署名付きWebhook。
3. 失敗時の自動返金と、ポリシーによる拒否への非課金。
4. 引き落とし前のプランチェックと、暗黙のエンジンフォールバックがないこと。
5. 顧客に提示できる課金単位。
6. プランに応じて拡大する、キーごとのレート制限。
7. モデル、価格、機能の実行時ディスカバリー。

このリストは、eroqを含めどのベンダーにも当てはめてください。ここで挙げた内容はすべて/docsにドキュメントがあり、料金は/pricingに掲載しています。

よくある質問

eroqの動画APIは同期型ですか、非同期型ですか？

非同期型です。POST /v1/videos/generationsがジョブIDを返すので、ジョブをポーリングするか、署名付きのvideo.generation.succeeded Webhookを受け取ります。一覧エンドポイントがワークスペースの最近のジョブを返すため、再起動してもレンダリングが失われることはありません。

動画のレンダリングが失敗した場合も課金されますか？

いいえ。失敗した生成は自動で返金され、コンテンツポリシーでブロックされたリクエストは課金なしでcontent_blockedを返します。プランの制限やエンジンの利用可否は、クレジットが動く前にチェックされます。

コードではなくエージェントから動画APIを呼び出せますか？

はい。https://eroq.ai/mcpのリモートMCPサーバーが、生成、ステータス確認、アカウントのツールをChatGPT、Claude、Cursor、Codexに提供します。またeroq CLIには、レンダリング結果をファイルとして保存するローカルのstdio MCPサーバーが付属しています。

APIキーを取得して、最初のジョブを送信しましょう：/signup