HedaAI 商品图 API
从商品照片生成 12 张专业电商图片(8 张主图 + 4 张 A+ 横幅)和完整 listing 文案 —— 可用程序调用,也可通过 MCP 直接由 AI agent 生成。
身份认证
在 hedaai.com/settings/api-keys 创建 API Key(任何账户均可;新账户赠送 $2.00 注册赠金 ≈ 2 个免费任务)。完整 Key(hda_live_…)及其 webhook secret(whsec_…)只在创建时显示一次,请妥善保存。Key 可命名、设置消费上限,并可随时吊销。
Authorization: Bearer hda_live_...
Key 以哈希形式存储,且只绑定你自己的账户 —— API Key 永远无法读取其他账户的数据。
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_name | string | 是 | 简短的商品名称。重要的 grounding 信号,尽量具体。 |
images | string[1–8] | 是 | 照片 URL(公开 http/https,每张 ≤15MB)和/或 base64 / data-URI。多角度照片能提升保真度。 |
aspect_ratio | string | 是 | 1:1、2:3、3:2、3:4、4:3、9:16、16:9。Amazon 主图使用 1:1。 |
category | string | 否 | 具体品类,例如 "vacuum cleaner replacement filter"。建议填写。 |
brand_name | string | 否 | 用于品牌故事图和 listing 文案。 |
key_features | string[≤10] | 否 | 必须展示的卖点。 |
specs | object | 否 | {material, colorway, key_components[], usage_context, use_scenarios[], dimensions[], scale}。建议填写 —— API 没有交互式确认环节,grounding 完全来自你提交的内容。 |
target_market | string | 否 | amazon_us(默认)· shopify · ebay |
copy_language | string | 否 | Listing 文案语言(en-US、de-DE、ja-JP…)。默认跟随目标市场。 |
aplus_format | string | 否 | banner(16:9,默认)· aplus_3_4 · aplus_9_16 · standard_aplus/premium(仅 Amazon) |
no_human_models | bool | 否 | true = 所有图片都不出现人物。 |
supplementary_text | string ≤5000 | 否 | 供 AI 阅读的自由文本规格 / 说明书节选。 |
callback_url | string | 否 | 终态回调 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}
状态流转:queued → processing → succeeded | partial_failed | failed | canceled。
- succeeded —— 12 张图全部完成;
product_id已生成;已扣费cost_cents: 100。 - partial_failed —— 部分图片失败;已成功的图片仍会保存为商品;不计费。
- failed / canceled —— 不计费;
error说明原因。
每 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"
}
M1–M8是 8 张主图,A1–A4是 A+ 横幅。- 付费账户在异步 2K 超分完成后会出现
url_2k(仅主图),可能比succeeded晚几分钟。 - 刚变为
succeeded时,个别图片记录可能短暂处于 pending —— 如果拿到的图片少于 12 张,请几秒后重新获取。 - URL 是永久的(由我们的 CDN 提供);外链和转存都没问题。
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.succeeded、task.partial_failed、task.failed、task.canceled。
{ "id": "evt_…", "type": "task.succeeded", "created_at": "2026-07-17T08:11:35Z",
"data": { /* task 对象 —— 结构与 GET /v1/tasks/{id} 相同 */ } }
签名遵循 Standard Webhooks 规范 —— header 为 webhook-id、webhook-timestamp、webhook-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_code | HTTP | 含义 |
|---|---|---|
bad_request | 400 | 参数无效 —— message 会指出具体字段(例如 images[2]: image download failed with HTTP 403)。 |
unauthorized | 401 | API Key 缺失/无效,或已被吊销。 |
insufficient_credits | 402 | 余额不足;响应包含 data.balance_cents。 |
spend_cap_exceeded | 403 | 该 Key 的消费上限已用尽。 |
account_disabled / email_not_verified / email_bounced | 403 | 账户级别的限制。 |
not_found | 404 | 任务/商品不存在,或属于其他账户。 |
idempotency_conflict | 409 | 相同 Idempotency-Key,body 不同。 |
concurrency_limit / api_capacity / rate_limited | 429 | 参见速率限制。 |
generation_failed / internal_error | 500 | 服务端故障;可带幂等 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
import time, requests
API = "https://hedaai.com/api/v1"
H = {"Authorization": "Bearer hda_live_..."}
# 1. 创建任务
task = requests.post(f"{API}/tasks",
headers={**H, "Idempotency-Key": "sku-8842-v1"},
json={"product_name": "stainless steel insulated water bottle",
"images": ["https://your-cdn.example.com/bottle.jpg"],
"aspect_ratio": "1:1"}).json()["data"]
# 2. 轮询直到终态
while task["status"] in ("queued", "processing"):
time.sleep(20)
task = requests.get(f"{API}/tasks/{task['task_id']}", headers=H).json()["data"]
# 3. 获取图片 + listing 文案
if task["status"] == "succeeded":
product = requests.get(f"{API}/products/{task['product_id']}", headers=H).json()["data"]
print([img["url"] for img in product["images"]])
print(product["listing_copy"]["title"])
const API = "https://hedaai.com/api/v1";
const H = { Authorization: "Bearer hda_live_...", "Content-Type": "application/json" };
// 1. 创建任务
let { data: task } = await (await fetch(`${API}/tasks`, {
method: "POST",
headers: { ...H, "Idempotency-Key": "sku-8842-v1" },
body: JSON.stringify({
product_name: "stainless steel insulated water bottle",
images: ["https://your-cdn.example.com/bottle.jpg"],
aspect_ratio: "1:1",
}),
})).json();
// 2. 轮询直到终态
while (["queued", "processing"].includes(task.status)) {
await new Promise(r => setTimeout(r, 20000));
({ data: task } = await (await fetch(`${API}/tasks/${task.task_id}`, { headers: H })).json());
}
// 3. 获取图片 + listing 文案
if (task.status === "succeeded") {
const { data: product } = await (await fetch(`${API}/products/${task.product_id}`, { headers: H })).json();
console.log(product.images.map(i => i.url), product.listing_copy.title);
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"time"
)
const api = "https://hedaai.com/api/v1"
type envelope struct {
Data struct {
TaskID string `json:"task_id"`
Status string `json:"status"`
ProductID string `json:"product_id"`
Images []struct {
URL string `json:"url"`
} `json:"images"`
ListingCopy struct {
Title string `json:"title"`
} `json:"listing_copy"`
} `json:"data"`
}
func call(method, url string, body []byte, extra map[string]string) (envelope, error) {
var out envelope
var rdr *bytes.Reader
if body != nil {
rdr = bytes.NewReader(body)
} else {
rdr = bytes.NewReader(nil)
}
req, err := http.NewRequest(method, url, rdr)
if err != nil {
return out, err
}
req.Header.Set("Authorization", "Bearer hda_live_...")
req.Header.Set("Content-Type", "application/json")
for k, v := range extra {
req.Header.Set(k, v)
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
return out, err
}
defer resp.Body.Close()
return out, json.NewDecoder(resp.Body).Decode(&out)
}
func main() {
// 1. 创建任务
payload, _ := json.Marshal(map[string]any{
"product_name": "stainless steel insulated water bottle",
"images": []string{"https://your-cdn.example.com/bottle.jpg"},
"aspect_ratio": "1:1",
})
task, err := call("POST", api+"/tasks", payload,
map[string]string{"Idempotency-Key": "sku-8842-v1"})
if err != nil {
panic(err)
}
// 2. 轮询直到终态
for task.Data.Status == "queued" || task.Data.Status == "processing" {
time.Sleep(20 * time.Second)
if task, err = call("GET", api+"/tasks/"+task.Data.TaskID, nil, nil); err != nil {
panic(err)
}
}
// 3. 获取图片 + listing 文案
if task.Data.Status == "succeeded" {
product, err := call("GET", api+"/products/"+task.Data.ProductID, nil, nil)
if err != nil {
panic(err)
}
for _, img := range product.Data.Images {
fmt.Println(img.URL)
}
fmt.Println(product.Data.ListingCopy.Title)
}
}
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import com.fasterxml.jackson.databind.*; // 任意 JSON 库均可
public class HedaAI {
static final String API = "https://hedaai.com/api/v1";
static final HttpClient CLIENT = HttpClient.newHttpClient();
static final ObjectMapper MAPPER = new ObjectMapper();
static JsonNode call(HttpRequest.Builder b) throws Exception {
HttpRequest req = b.header("Authorization", "Bearer hda_live_...")
.header("Content-Type", "application/json")
.build();
String body = CLIENT.send(req, HttpResponse.BodyHandlers.ofString()).body();
return MAPPER.readTree(body).path("data");
}
public static void main(String[] args) throws Exception {
// 1. 创建任务
JsonNode task = call(HttpRequest.newBuilder(URI.create(API + "/tasks"))
.header("Idempotency-Key", "sku-8842-v1")
.POST(HttpRequest.BodyPublishers.ofString("""
{"product_name":"stainless steel insulated water bottle",
"images":["https://your-cdn.example.com/bottle.jpg"],
"aspect_ratio":"1:1"}""")));
// 2. 轮询直到终态
String status = task.path("status").asText();
while (status.equals("queued") || status.equals("processing")) {
Thread.sleep(Duration.ofSeconds(20));
task = call(HttpRequest.newBuilder(
URI.create(API + "/tasks/" + task.path("task_id").asText())).GET());
status = task.path("status").asText();
}
// 3. 获取图片 + listing 文案
if (status.equals("succeeded")) {
JsonNode product = call(HttpRequest.newBuilder(
URI.create(API + "/products/" + task.path("product_id").asText())).GET());
product.path("images").forEach(img -> System.out.println(img.path("url").asText()));
System.out.println(product.path("listing_copy").path("title").asText());
}
}
}
<?php
$api = "https://hedaai.com/api/v1";
$headers = ["Authorization: Bearer hda_live_...", "Content-Type: application/json"];
function call($method, $url, $headers, $body = null) {
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $headers]);
if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
$res = json_decode(curl_exec($ch), true); curl_close($ch);
return $res["data"];
}
// 1. 创建任务
$task = call("POST", "$api/tasks", array_merge($headers, ["Idempotency-Key: sku-8842-v1"]), [
"product_name" => "stainless steel insulated water bottle",
"images" => ["https://your-cdn.example.com/bottle.jpg"],
"aspect_ratio" => "1:1",
]);
// 2. 轮询直到终态
while (in_array($task["status"], ["queued", "processing"])) {
sleep(20);
$task = call("GET", "$api/tasks/{$task['task_id']}", $headers);
}
// 3. 获取图片 + listing 文案
if ($task["status"] === "succeeded") {
$product = call("GET", "$api/products/{$task['product_id']}", $headers);
foreach ($product["images"] as $img) echo $img["url"], "\n";
echo $product["listing_copy"]["title"], "\n";
}
MCP 服务器(面向 AI agent)
HedaAI 提供托管的 Model Context Protocol 服务器,agent 可直接生成商品图:
- Endpoint:
https://hedaai.com/api/v1/mcp(Streamable HTTP,无状态) - 认证:同样使用
Authorization: Bearer hda_live_…header - 工具:
create_product_shoot·get_task·get_product·get_balance
claude mcp add --transport http hedaai https://hedaai.com/api/v1/mcp \
--header "Authorization: Bearer $HEDAAI_API_KEY"
{
"mcpServers": {
"hedaai": {
"url": "https://hedaai.com/api/v1/mcp",
"headers": { "Authorization": "Bearer hda_live_..." }
}
}
}
生成是异步的: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)。