開発者 api.md llms.txt
🌐 日本語
APIキーを取得

HedaAI商品画像API

商品写真から12枚のプロ品質EC画像(メイン画像8枚、A+バナー4枚)と完全なリスティングコピーを生成します — プログラムから、あるいはMCP経由でAIエージェントから直接。

$1.00 / 商品成功時のみ課金
約10分非同期: 作成 → ポーリング → 取得
永続ストレージ結果はアカウントに保存され、URLの有効期限はありません
MCP標準搭載AIエージェント向けホスト型サーバー
ベースURL: https://hedaai.com/api/v1  ·  エージェント向けドキュメントミラー: /developers/api.md · /developers/llms.txt

認証

APIキーはhedaai.com/settings/api-keysで作成できます(どのアカウントでも利用可能。新規アカウントには$2.00のサインアップボーナスが付与され、≈2タスク分を無料で実行できます)。キー全文(hda_live_…)とそのウェブフックシークレット(whsec_…)は作成時に一度だけ表示されます — 安全に保管してください。キーには名前と上限額を設定でき、いつでも失効させられます。

Authorization: Bearer hda_live_...

キーはハッシュ化して保存され、ご自身のアカウントにのみ紐づきます。APIキーが他のアカウントのデータを読み取ることはありません。

サンドボックスモード(無料テスト): アカウントで実際の支払いが行われるまで、生成画像にはウォーターマークが入り、2Kアップスケールは行われません。それ以外の動作はすべて同一です(GET /v1/account"mode": "sandbox_watermarked"を返します)。初回の支払いにより、それまでに生成したすべての商品のウォーターマークが自動的に削除されます。

上限額: 各キーには任意でspend_cap_centsを設定できます(デフォルト: 無制限)。上限に達すると、タスク作成はspend_cap_exceeded(403)で失敗します。

レスポンスエンベロープ

{ "status": 200, "code": 200, "message": "", "data": { … } }

エラーにはプログラムでの判定用にerror_codeが追加されます。転送エラーとタスク失敗の違い: HTTP 4xx/5xxはリクエストが失敗したことを意味します。生成中に失敗したタスクはHTTPエラーではありません。ポーリングは200とstatus: "failed"およびerrorフィールドを返し、課金は発生しません。

クイックスタート

# 1. タスクを作成
curl -X POST https://hedaai.com/api/v1/tasks \
  -H "Authorization: Bearer $HEDAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-attempt-1" \
  -d '{
    "product_name": "stainless steel insulated water bottle",
    "images": ["https://your-cdn.example.com/bottle-front.jpg"],
    "aspect_ratio": "1:1",
    "category": "insulated water bottle 750ml",
    "target_market": "amazon_us"
  }'
# → data.task_id = "3f8a…", data.status = "queued"

# 2. 終了状態になるまで15–30秒ごとにポーリング
curl -H "Authorization: Bearer $HEDAAI_API_KEY" https://hedaai.com/api/v1/tasks/3f8a…
# → data.status = "succeeded", data.product_id = "9c1b…"

# 3. 完成した商品を取得(画像12枚のURL + リスティングコピー)
curl -H "Authorization: Bearer $HEDAAI_API_KEY" https://hedaai.com/api/v1/products/9c1b…

POST/v1/tasks

生成タスクを作成します。任意のヘッダー: Idempotency-Key(≤64文字、下記参照)。

フィールド必須備考
product_namestringはい短い商品名。グラウンディングの重要なシグナルです。具体的に記述してください。
imagesstring[1–8]はい写真URL(公開http/https、各≤15MB)および/またはbase64 / データURI。複数アングルの写真は商品の忠実度を高めます。
aspect_ratiostringはい1:12:33:23:44:39:1616:9。Amazonのメイン画像は1:1を使用します。
categorystringいいえ具体的なカテゴリー。例: "vacuum cleaner replacement filter"。推奨。
brand_namestringいいえブランドストーリー画像とリスティングコピーに反映されます。
key_featuresstring[≤10]いいえ必ず訴求したいセールスポイント。
specsobjectいいえ{material, colorway, key_components[], usage_context, use_scenarios[], dimensions[], scale}。推奨 — APIには対話的なレビュー工程がないため、グラウンディングは送信された内容のみに依存します。
target_marketstringいいえamazon_us(デフォルト)· shopify · ebay
copy_languagestringいいえリスティングコピーのロケール(en-USde-DEja-JP、…)。デフォルトはターゲット市場に従います。
aplus_formatstringいいえbanner(16:9、デフォルト)· aplus_3_4 · aplus_9_16 · standard_aplus/premium(Amazonのみ)
no_human_modelsboolいいえtrue = すべての画像に人物を含めません。
supplementary_textstring ≤5000いいえAIが読み取る自由記述の仕様・マニュアル抜粋。
callback_urlstringいいえ終了ステータス通知用のウェブフック(ウェブフック)。

タスクオブジェクトを返します:

{
  "task_id": "3f8a…", "status": "queued", "progress": 0,
  "queue_position": 2, "eta_seconds": 840, "cost_cents": 0,
  "created_at": "2026-07-17T08:00:00Z",
  "urls": { "get": "/api/v1/tasks/3f8a…", "cancel": "/api/v1/tasks/3f8a…/cancel" }
}

GET/v1/tasks/{task_id}

ステータスのライフサイクル: queuedprocessingsucceeded | partial_failed | failed | canceled

15–30秒ごとにポーリングしてください。queue_position / eta_secondsはキュー待ち中に設定されます。

POST/v1/tasks/{task_id}/cancel

タスクをキャンセルします。キュー待ち中は無料です。すでに完了したタスクには影響しません(冪等)。

GET/v1/products/{product_id}

{
  "product_id": "9c1b…", "name": "stainless steel insulated water bottle",
  "target_market": "amazon_us", "aspect_ratio": "1:1", "watermarked": false,
  "listing_copy": {
    "title": "…", "bullet_points": ["…","…","…","…","…"], "description": "…",
    "search_terms": "…", "meta_title": "…", "meta_description": "…", "language": "en"
  },
  "images": [
    { "slice_id": "M1", "section": "main", "url": "https://images.hedaai.com/…",
      "url_2k": "https://images.hedaai.com/…", "width": 2048, "height": 2048, "sort_order": 1 }
  ],
  "created_at": "2026-07-17T08:11:32Z"
}

GET/v1/account

{
  "balance_cents": 1250, "paid_balance_cents": 1000, "bonus_balance_cents": 250,
  "has_paid": true, "mode": "live", "price_per_task_cents": 100,
  "key": { "name": "prod-integration", "key_prefix": "hda_live_ab12…cd34",
           "spend_cap_cents": null, "spent_cents": 700 }
}

冪等性

POST /v1/tasksIdempotency-Keyヘッダー(≤64文字)を指定します。同じキーと同じボディで再試行すると、重複タスクを作成(そして課金)せずに元のタスクを返します。同じキーで異なるボディの場合は409 idempotency_conflictを返します。エージェントや自動化では強く推奨されます。ネットワーク再試行が二重課金の心配なく行えます。

ウェブフック

タスク作成時にcallback_urlを設定すると、終了ステータス時にPOSTを受け取れます。イベント: task.succeededtask.partial_failedtask.failedtask.canceled

{ "id": "evt_…", "type": "task.succeeded", "created_at": "2026-07-17T08:11:35Z",
  "data": { /* タスクオブジェクト — GET /v1/tasks/{id} と同じ形式 */ } }

署名はStandard Webhooks仕様に準拠します。ヘッダーはwebhook-idwebhook-timestampwebhook-signature: v1,<base64>です。キーのwebhook_secretで検証してください:

import hmac, hashlib, base64

def verify(secret, msg_id, timestamp, body: bytes, signature_header):
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{timestamp}.".encode() + body,
                                         hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(expected, s.split(",", 1)[1])
               for s in signature_header.split() if s.startswith("v1,"))

2xxを速やかに返してください(重い処理は非同期で)。配信は即時1回、その後3s / 6s / 12sで再試行し、以降は失敗として記録されます(ポーリングは引き続き利用可能)。古いタイムスタンプ(>5分)は拒否し、idで重複排除してください。callback_urlは公開http(s)エンドポイントである必要があります。プライベート/内部アドレスは拒否されます。

レート制限と同時実行数

制限超過時
キーあたりのリクエスト数120 / 分(全エンドポイント)429 rate_limitedRateLimit-Limit / -Remaining / -Resetヘッダーを確認
キーあたりの実行中タスク数2(queued + processing)429 concurrency_limit — タスクの完了を待つ
プラットフォームAPI容量動的429 api_capacity — 数分後に再試行

生成は負荷が高く(1タスクあたり13–20回のAI画像呼び出し)、スループットはリクエスト数ではなく実行中タスクのスロット数で決まります。より多くの同時実行が必要な場合はお問い合わせください

エラー

error_codeHTTP意味
bad_request400パラメータが不正です。メッセージが該当フィールドを示します(例: images[2]: image download failed with HTTP 403)。
unauthorized401APIキーが未指定/不正、またはキーが失効しています。
insufficient_credits402残高が不足しています。data.balance_centsが含まれます。
spend_cap_exceeded403このキーの上限額を使い切りました。
account_disabled / email_not_verified / email_bounced403アカウントレベルの制限です。
not_found404タスク/商品が存在しないか、別のアカウントに属しています。
idempotency_conflict409同じIdempotency-Keyで異なるボディです。
concurrency_limit / api_capacity / rate_limited429制限を参照してください。
generation_failed / internal_error500サーバー側の障害です。冪等キーを付けて再試行して問題ありません。

コード例

タスクの作成、終了までのポーリング、完成した商品の取得という一連の流れを、お好みの言語で。

API=https://hedaai.com/api/v1

# 1. タスクを作成
TASK_ID=$(curl -sS -X POST "$API/tasks" \
  -H "Authorization: Bearer $HEDAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-8842-v1" \
  -d '{"product_name":"stainless steel insulated water bottle",
       "images":["https://your-cdn.example.com/bottle.jpg"],
       "aspect_ratio":"1:1"}' | jq -r .data.task_id)

# 2. 終了状態になるまでポーリング
while :; do
  TASK=$(curl -sS -H "Authorization: Bearer $HEDAAI_API_KEY" "$API/tasks/$TASK_ID")
  STATUS=$(echo "$TASK" | jq -r .data.status)
  [ "$STATUS" = "queued" ] || [ "$STATUS" = "processing" ] || break
  sleep 20
done

# 3. 画像とリスティングコピーを取得
if [ "$STATUS" = "succeeded" ]; then
  PRODUCT_ID=$(echo "$TASK" | jq -r .data.product_id)
  curl -sS -H "Authorization: Bearer $HEDAAI_API_KEY" "$API/products/$PRODUCT_ID" \
    | jq -r '.data.images[].url, .data.listing_copy.title'
fi

MCPサーバー(AIエージェント向け)

HedaAIはホスト型のModel Context Protocolサーバーを提供しており、エージェントから直接商品画像を生成できます:

claude mcp add --transport http hedaai https://hedaai.com/api/v1/mcp \
  --header "Authorization: Bearer $HEDAAI_API_KEY"

生成は非同期です。エージェントはcreate_product_shootを呼び出し(任意でidempotency_keyを指定)、終了状態になるまで30–60秒ごとにget_taskをポーリングし、その後get_productで画像URLとリスティングコピーを取得します。OAuthが必須のクライアント(claude.aiのカスタムコネクタなど)は未対応です。Claude Code、Cursor、エージェントSDKなど、APIキーに対応したクライアントをご利用ください。

料金

項目価格
商品撮影 — 画像12枚 + リスティングコピー$1.00、成功時のみ課金
サインアップボーナス$2.00(≈2タスク分を無料で実行可能。初回支払いまではウォーターマーク付き)
残高チャージhedaai.comで$10–$1000。≥$50で+5%ボーナス、≥$100で+10%

残高は無期限です。サブスクリプションはありません。最新の価格は常にGET /v1/accountprice_per_task_cents)で確認できます。