AI画像APIを制作会社のパイプラインに組み込む: キー、台帳、アーカイブ

APIリファレンスが教えてくれるのは1枚の画像の作り方です。制作会社の課題は別物です。何千枚もの画像、十数社のクライアント、ボタンを押す3人のスタッフ、そして月末に誰が何を使ったのかを尋ねる経理担当が1人。どれも難しくはありませんが、最初の1週間でどこかを間違えるのは簡単です。ここでは6つのルールを紹介します。どれも「こう動いてほしい」ではなく、APIの実際の挙動から導いたものです。まだ最初のリクエストを送っていないなら、APIの入門記事から始めてください。

ルール1: クライアントごとにキーを1つ、その背後に財布は1つ

キーはAPI Consoleで作成し、それぞれに名前を付けます。完全なキーが表示されるのは一度だけです。名前はクライアントに合わせて付けましょう。漏えいしたキーや契約が終わったクライアントのキーは個別に無効化でき、ほかのキーはそのまま動き続けます。ただし、キーはお金を分けてはくれません。アカウントのキーはすべて同じコイン残高を使います。2社のクライアントに絶対に残高を共有させたくないなら、アカウントを2つにする必要があり、後からアカウント間でコインを移すことはできません。

ルール2: 自社のジョブIDで紐づける自前の台帳

一覧エンドポイントが返すのはアカウント全体で、スタジオで作った画像も含まれます。1つのキーの作業だけではありません。そこで自前の台帳を持ちましょう。クライアント、ジョブ、生成ID、課金されたコイン。これらを結びつけるいちばん確実な方法がIdempotency-Keyヘッダーです。自社のジョブIDから作れば、接続が切れた後にリトライしたリクエストは2回目の課金をせず、既存の生成を返します。キーはあなたのアカウント内だけでなくサービス全体で照合されるので、自社固有のプレフィックスを付けてください。ランダムな文字列で十分です。

POST /v1/api/images
Authorization: Bearer fk_live_key_for_client_a
Idempotency-Key: 7f1c2b90-client-a-deck-0042

{
  "prompt": "a linen shirt on a wooden hanger, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

レスポンスは生成のIDとcoinsChargedを含む202です。ほかの処理をする前に、両方を台帳に書き込んでください。

ルール3: 待たずにポーリングする

生成はキューに入り、バックグラウンドで実行されます。ステータスは控えめな間隔でポーリングし(キューにある間はレスポンスのetaMsに目安が入ります)、ジョブは1つずつではなく複数を同時に投げてください。APIはスタジオよりもアカウントあたりの並列ジョブ数を多く認めています。それがAPIの本来の使い方だからです。

GET /v1/api/images/{id}          -> "queued", "generating", then "succeeded",
                                    or "failed" / "refunded" with refunded: true
GET /v1/api/images/{id}/content  -> the bytes, until the retention window ends
                                    (after that: 410 BYTES_EXPIRED)

ルール4: 失敗はデータとして扱う

失敗した生成はコインを自動で返金し、そのことをrefundedで知らせます。failureCodeは短い固定リストのいずれかです。TIMEOUTとVENDOR_ERRORは時間をおいて1回リトライする価値があり、MODERATION_REJECTEDはプロンプトを繰り返すのではなく書き直す必要があることを意味し、UNKNOWNはそれ以外すべてです。コードは台帳に記録しましょう。ブリーフが何度もモデレーションで弾かれるクライアントには、リトライのループではなく話し合いが必要です。リトライの経済性は料金と失敗についての記事で解説しています。

ルール5: 成功したらすぐにアーカイブする

APIはアセットライブラリではありません。完成したファイルは製品ページに記載された保存期間が終わると削除され、その後のコンテンツのリクエストは410 BYTES_EXPIREDを返します。成功した画像はすべて、台帳のクライアントとジョブの下ですぐに自社のストレージへダウンロードしてください。画像を私たちのもとに一切残したくないクライアントの場合は、アーカイブ後にAPIから削除できます。

ルール6: 制限はコードで確認し、納品前に人の目を入れる

キーごとにリクエストレートがあり、アカウントには1日あたりの画像枠があります。どちらも1回の呼び出しで取得できるので、バッチジョブは途中で失敗する代わりに、開始前に確認できます。

GET /v1/api/me
-> { "keyName": "client-a", "coins": ..., "rateLimitPerMin": ..., "dailyImagesRemaining": ... }

具体的な数値は製品ページに載っています。そして、クライアントに何かを届ける前には必ず誰かが目を通してください。モデルは手に6本の指を描いたり、看板に間違った文字を入れたりすることがあり、自動化されたパイプラインはそれを良い画像と同じ速さで届けてしまいます。

APIが制作会社のためにしてくれないこと

サブアカウントも、クライアント別の残高も、キーごとの利用レポートもありません。その帳簿付けはあなたの仕事です。SLA(サービスレベル契約)も保証された納期もないので、測定していない所要時間をクライアントに約束しないでください。また、AI画像は誰のものかで説明しているとおり、生成した画像が著作権の意味であなたのものになるわけではありません。ただし商用利用は認められており、私たちが取り分を受け取ることもありません。そして実在の人物の顔には、リクエストがどの経路で届いたとしても、その本人の許可が必要です。

これらすべてを支えるコインの予算についてはチームが実際に使う量で取り上げています。手作業で画像を作るためのスタジオはFellowi Imagesです。