APIでAltGenをアップロードパイプラインに組み込む

ダッシュボードは単発のバッチには便利ですが、画像がプロダクト内で常に動いているなら、代替テキストの生成に人手を挟みたくないはずです。ここでは、AltGenを自分のアップロードフローに直接組み込む方法を解説します。

スコープ付きAPIキーを取得する

Settings → API Keysから作成します。キーはワークスペースごとにスコープされ、任意で有効期限を設定でき、他のインテグレーションに影響を与えずに無効化できます。

curl -X POST https://api.altgen.io/v1/images/generate \
  -H "Authorization: Bearer $ALTGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cdn.yourstore.com/sneaker.jpg",
    "preset": "ecommerce",
    "style": "concise",
    "languages": ["en", "de", "tr"]
  }'

レスポンスには、主要な代替テキストに加えて、リクエストした言語ごとの翻訳が返ってきます。

{
  "altText": "Burgundy low-top sneaker with a white sole, floating on a yellow background",
  "translations": { "de": "…", "tr": "…" },
  "status": "completed",
  "creditsCost": 1
}

結果を受け取る2つの方法

同期 — エンドポイントを呼び出してレスポンスを待つ。シンプルですが、単一画像や少量の場合にのみ意味があります。

Webhook — 規模のあるものには、代わりに生成イベントを購読します。画像の処理が完了するとすぐにAltGenがエンドポイントにペイロードを送信するため、アップロードハンドラーが500枚のバッチを待ち続ける必要はありません。

典型的なCMSインテグレーション

編集者がCMSに画像をアップロードする。
アップロードハンドラーが画像URLとともにPOST /v1/images/generateを呼び出す。
AltGenが処理し、完了時にエンドポイントへWebhookを送信する。
ハンドラーが返された代替テキストを、画像のメタデータフィールドに直接書き込む。

ダッシュボードなし、手動レビューのステップなし、誰かがフィールドの入力を忘れたせいで代替テキストなしで公開される画像もありません。

バッチを監視せずに失敗を再試行する

生成が失敗した場合は、すべてを再送信する代わりにPATCH /v1/images/{id}/retryを呼び出します。これは一括バッチが内部で使うのと同じ仕組みで、APIを通じて個々の画像を管理するケース向けに公開されているだけです。

これが全体の仕様です。生成・一覧・更新・再試行のための1つのエンドポイントと、ポーリングしたくない場合のWebhook。完全なリファレンスはAPIドキュメントにあります。