HedaAI商品画像API
商品写真から12枚のプロ品質EC画像(メイン画像8枚、A+バナー4枚)と完全なリスティングコピーを生成します — プログラムから、あるいはMCP経由でAIエージェントから直接。
認証
APIキーはhedaai.com/settings/api-keysで作成できます(どのアカウントでも利用可能。新規アカウントには$2.00のサインアップボーナスが付与され、≈2タスク分を無料で実行できます)。キー全文(hda_live_…)とそのウェブフックシークレット(whsec_…)は作成時に一度だけ表示されます — 安全に保管してください。キーには名前と上限額を設定でき、いつでも失効させられます。
Authorization: Bearer hda_live_...
キーはハッシュ化して保存され、ご自身のアカウントにのみ紐づきます。APIキーが他のアカウントのデータを読み取ることはありません。
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_name | string | はい | 短い商品名。グラウンディングの重要なシグナルです。具体的に記述してください。 |
images | string[1–8] | はい | 写真URL(公開http/https、各≤15MB)および/またはbase64 / データ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 | いいえ | ブランドストーリー画像とリスティングコピーに反映されます。 |
key_features | string[≤10] | いいえ | 必ず訴求したいセールスポイント。 |
specs | object | いいえ | {material, colorway, key_components[], usage_context, use_scenarios[], dimensions[], scale}。推奨 — APIには対話的なレビュー工程がないため、グラウンディングは送信された内容のみに依存します。 |
target_market | string | いいえ | amazon_us(デフォルト)· shopify · ebay |
copy_language | string | いいえ | リスティングコピーのロケール(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 | いいえ | 終了ステータス通知用のウェブフック(ウェブフック)。 |
タスクオブジェクトを返します:
{
"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+バナーです。url_2kは有料アカウントで非同期の2Kアップスケールが完了すると表示されます(メイン画像のみ)。succeededから数分遅れることがあります。succeededの直後は画像の行が一時的に保留中になることがあります — 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ヘッダー(≤64文字)を指定します。同じキーと同じボディで再試行すると、重複タスクを作成(そして課金)せずに元のタスクを返します。同じキーで異なるボディの場合は409 idempotency_conflictを返します。エージェントや自動化では強く推奨されます。ネットワーク再試行が二重課金の心配なく行えます。
ウェブフック
タスク作成時に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": { /* タスクオブジェクト — GET /v1/tasks/{id} と同じ形式 */ } }
署名はStandard Webhooks仕様に準拠します。ヘッダーはwebhook-id、webhook-timestamp、webhook-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_limited — RateLimit-Limit / -Remaining / -Resetヘッダーを確認 |
| キーあたりの実行中タスク数 | 2(queued + processing) | 429 concurrency_limit — タスクの完了を待つ |
| プラットフォームAPI容量 | 動的 | 429 api_capacity — 数分後に再試行 |
生成は負荷が高く(1タスクあたり13–20回のAI画像呼び出し)、スループットはリクエスト数ではなく実行中タスクのスロット数で決まります。より多くの同時実行が必要な場合はお問い合わせください。
エラー
| error_code | HTTP | 意味 |
|---|---|---|
bad_request | 400 | パラメータが不正です。メッセージが該当フィールドを示します(例: images[2]: image download failed with HTTP 403)。 |
unauthorized | 401 | APIキーが未指定/不正、またはキーが失効しています。 |
insufficient_credits | 402 | 残高が不足しています。data.balance_centsが含まれます。 |
spend_cap_exceeded | 403 | このキーの上限額を使い切りました。 |
account_disabled / email_not_verified / email_bounced | 403 | アカウントレベルの制限です。 |
not_found | 404 | タスク/商品が存在しないか、別のアカウントに属しています。 |
idempotency_conflict | 409 | 同じIdempotency-Keyで異なるボディです。 |
concurrency_limit / api_capacity / rate_limited | 429 | 制限を参照してください。 |
generation_failed / internal_error | 500 | サーバー側の障害です。冪等キーを付けて再試行して問題ありません。 |
コード例
タスクの作成、終了までのポーリング、完成した商品の取得という一連の流れを、お好みの言語で。
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
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. 画像とリスティングコピーを取得
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. 画像とリスティングコピーを取得
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. 画像とリスティングコピーを取得
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. 画像とリスティングコピーを取得
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. 画像とリスティングコピーを取得
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エージェント向け)
HedaAIはホスト型のModel Context Protocolサーバーを提供しており、エージェントから直接商品画像を生成できます:
- エンドポイント:
https://hedaai.com/api/v1/mcp(Streamable HTTP、ステートレス) - 認証: 同じ
Authorization: Bearer hda_live_…ヘッダー - ツール:
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_..." }
}
}
}
生成は非同期です。エージェントは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/account(price_per_task_cents)で確認できます。