开发者 api.md llms.txt
🌐 简体中文
获取 API Key

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 Key(任何账户均可;新账户赠送 $2.00 注册赠金 ≈ 2 个免费任务)。完整 Key(hda_live_…)及其 webhook secret(whsec_…)只在创建时显示一次,请妥善保存。Key 可命名、设置消费上限,并可随时吊销。

Authorization: Bearer hda_live_...

Key 以哈希形式存储,且只绑定你自己的账户 —— API Key 永远无法读取其他账户的数据。

Sandbox 模式(免费测试):在账户完成首次真实支付前,生成的图片带水印且没有 2K 超分,其余行为完全一致(GET /v1/account 会返回 "mode": "sandbox_watermarked")。首次支付后,此前生成的所有商品图会自动去除水印。

消费上限:每个 Key 可选设置 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(Webhook)。

返回一个 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 字符)。使用相同 key 和相同 body 重试会返回原任务,而不是创建(并最终扣费)一个重复任务。相同 key 配不同 body 会返回 409 idempotency_conflict。强烈建议 agent 和自动化场景使用 —— 网络重试因此不会重复扣费。

Webhook

创建任务时设置 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 规范 —— header 为 webhook-idwebhook-timestampwebhook-signature: v1,<base64>。用该 Key 的 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 获取)。请拒绝过期时间戳(>5 分钟)并按 id 去重。callback_url 必须是公网 http(s) endpoint —— 私有/内网地址会被拒绝。

速率限制 & 并发

限制项取值超限时
每个 Key 的请求数120 / 分钟(所有 endpoint 合计)429 rate_limited —— 查看 RateLimit-Limit / -Remaining / -Reset header
每个 Key 的进行中任务数2(queued + processing)429 concurrency_limit —— 等待任务完成
平台 API 容量动态调整429 api_capacity —— 几分钟后重试

生成过程很重(每个任务 13–20 次 AI 出图调用),因此吞吐由进行中任务槽位决定,而非请求速率。需要更高并发?联系我们

错误

error_codeHTTP含义
bad_request400参数无效 —— message 会指出具体字段(例如 images[2]: image download failed with HTTP 403)。
unauthorized401API Key 缺失/无效,或已被吊销。
insufficient_credits402余额不足;响应包含 data.balance_cents
spend_cap_exceeded403该 Key 的消费上限已用尽。
account_disabled / email_not_verified / email_bounced403账户级别的限制。
not_found404任务/商品不存在,或属于其他账户。
idempotency_conflict409相同 Idempotency-Key,body 不同。
concurrency_limit / api_capacity / rate_limited429参见速率限制
generation_failed / internal_error500服务端故障;可带幂等 key 安全重试。

代码示例

完整流程 —— 创建任务、轮询至终态、获取完成的商品 —— 用你选择的语言实现。

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 Key 的客户端,例如 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)。