開發者 api.md llms.txt
🌐 繁體中文
取得 API 金鑰

HedaAI 商品圖 API

從商品照片生成 12 張專業電商圖片(8 張主圖 + 4 張 A+ 橫幅)與完整 listing 文案 — 可用程式呼叫,也可透過 MCP 直接由你的 AI agent 生成。

$1.00 / 件僅在成功時計費
~10 分鐘非同步:建立 → 輪詢 → 取得
永久儲存結果保存在你的帳戶,URL 不會過期
內建 MCP為 AI agent 提供的託管伺服器
Base URL: https://hedaai.com/api/v1  ·  給 agent 的文件鏡像: /developers/api.md · /developers/llms.txt

身分驗證

hedaai.com/settings/api-keys 建立 API 金鑰(任何帳戶皆可;新帳戶可獲得 $2.00 註冊贈金 ≈ 2 次免費任務)。完整金鑰(hda_live_…)與其 webhook secret(whsec_…)只在建立時顯示一次 — 請妥善保存。金鑰可命名、設定消費上限,並隨時撤銷。

Authorization: Bearer hda_live_...

金鑰以雜湊形式儲存,且僅綁定你的帳戶 — API 金鑰永遠無法讀取其他帳戶的資料。

Sandbox 模式(免費測試):在你的帳戶完成首次真實付款前,生成的圖片會帶浮水印且沒有 2K 超解析 — 其餘行為完全相同(GET /v1/account 會回報 "mode": "sandbox_watermarked")。首次付款後,先前已生成的所有商品都會自動移除浮水印。

消費上限:每把金鑰都可選擇性設定 spend_cap_cents(預設:無上限)。達到上限後,建立任務會以 spend_cap_exceeded(403)失敗。

回應結構

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

錯誤會額外帶上 error_code 供程式比對。傳輸錯誤 vs 任務失敗: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–30s 輪詢一次直到終態
curl -H "Authorization: Bearer $HEDAAI_API_KEY" https://hedaai.com/api/v1/tasks/3f8a…
# → data.status = "succeeded", data.product_id = "9c1b…"

# 3. 取得完成的商品(12 個圖片URL + listing 文案)
curl -H "Authorization: Bearer $HEDAAI_API_KEY" https://hedaai.com/api/v1/products/9c1b…

POST/v1/tasks

建立生成任務。選用 header:Idempotency-Key(≤64 字元,見下文)。

欄位型別必填說明
product_namestring簡短的商品名稱。重要的 grounding 訊號 — 請寫得具體。
imagesstring[1–8]照片URL(公開 http/https,每張 ≤15MB)與/或 base64 / data-URI。多角度照片能提升保真度。
aspect_ratiostring1:12:33:23:44:39:1616:9。Amazon 主圖使用 1:1。
categorystring具體的品類,例如 "vacuum cleaner replacement filter"。建議填寫。
brand_namestring用於品牌故事圖與 listing 文案。
key_featuresstring[≤10]必須呈現的賣點。
specsobject{material, colorway, key_components[], usage_context, use_scenarios[], dimensions[], scale}。建議填寫 — 此 API 沒有互動式確認步驟,grounding 全部來自你送出的內容。
target_marketstringamazon_us(預設)· shopify · ebay
copy_languagestringListing 文案語系(en-USde-DEja-JP…)。預設依目標市場而定。
aplus_formatstringbanner(16:9,預設)· aplus_3_4 · aplus_9_16 · standard_aplus/premium(僅限 Amazon)
no_human_modelsbooltrue = 所有圖片皆不出現人物。
supplementary_textstring ≤5000自由文字的規格/說明書摘錄,供 AI 閱讀。
callback_urlstring終態狀態的 webhook(Webhooks)。

回傳一個 task 物件

{
  "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/tasks 帶上 Idempotency-Key header(≤64 字元)。以相同金鑰與相同 body 重試會回傳原本的任務,而不會建立(並最終計費)重複任務。相同金鑰搭配不同 body 會回傳 409 idempotency_conflict。強烈建議 agent 與自動化流程使用 — 網路重試便不會重複扣款。

Webhooks

建立任務時設定 callback_url,即可在終態時收到 POST。事件:task.succeededtask.partial_failedtask.failedtask.canceled

{ "id": "evt_…", "type": "task.succeeded", "created_at": "2026-07-17T08:11:35Z",
  "data": { /* task 物件 — 與 GET /v1/tasks/{id} 結構相同 */ } }

簽章遵循 Standard Webhooks 規範 — headers 為 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(繁重工作改以非同步處理)。投遞方式:立即嘗試一次,之後於 3s / 6s / 12s 重試,再失敗則標記為失敗(仍可用 polling 取得結果)。請拒絕過期的 timestamp(>5 分鐘)並以 id 去重。callback_url 必須是公開的 http(s) endpoint — 私有/內網位址會被拒絕。

速率限制與並行數

限制超過時
每把金鑰的請求數120 / 分鐘(所有 endpoint)429 rate_limited — 請檢查 RateLimit-Limit / -Remaining / -Reset headers
每把金鑰進行中的任務數2(queued + processing)429 concurrency_limit — 等待任務完成
平台 API 容量動態429 api_capacity — 幾分鐘後重試

生成相當耗資源(每個任務 13–20 次 AI 圖片呼叫),因此吞吐量取決於進行中的任務名額,而非請求速率。需要更高的並行數?聯絡我們

錯誤

error_codeHTTP含義
bad_request400參數無效 — 訊息會指出具體欄位(例如 images[2]: image download failed with HTTP 403)。
unauthorized401缺少/無效的 API 金鑰,或金鑰已撤銷。
insufficient_credits402餘額不足;回應會含 data.balance_cents
spend_cap_exceeded403此金鑰的消費上限已用盡。
account_disabled / email_not_verified / email_bounced403帳戶層級的限制。
not_found404任務/商品不存在,或屬於其他帳戶。
idempotency_conflict409相同的 Idempotency-Key,不同的 body。
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. 取得圖片 + listing 文案
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 agent)

HedaAI 提供託管的 Model Context Protocol 伺服器,讓 agent 可以直接生成商品圖:

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

生成是非同步的:agent 呼叫 create_product_shoot(可選擇帶上 idempotency_key),每 30–60s 輪詢 get_task 直到終態,再以 get_product 取得圖片URL與 listing 文案。目前尚不支援必須使用 OAuth 的用戶端(例如 claude.ai 自訂連接器)— 請改用支援 API 金鑰的用戶端,例如 Claude Code、Cursor 或 agent SDK。

定價

項目價格
商品拍攝 — 12 張圖片 + listing 文案$1.00,僅在成功時計費
註冊贈金$2.00(≈ 2 次免費任務,首次付款前帶浮水印)
餘額儲值hedaai.com 儲值 $10–$1000;≥$50 +5% 贈金,≥$100 +10%

餘額永不過期。無訂閱制。即時價格隨時可透過 GET /v1/account 取得(price_per_task_cents)。