HedaAI Produktbilder-API
12 professionelle E-Commerce-Bilder (8 Hauptbilder + 4 A+ Banner) plus vollständigen Listing-Text aus Produktfotos generieren — programmatisch oder direkt aus dem KI-Agenten per MCP.
https://hedaai.com/api/v1 · Doku-Mirrors für Agenten: /developers/api.md · /developers/llms.txtAuthentifizierung
API-Key unter hedaai.com/settings/api-keys erstellen (jeder Account funktioniert; neue Accounts erhalten $2.00 Startguthaben ≈ 2 kostenlose Tasks). Der vollständige Key (hda_live_…) und sein Webhook-Secret (whsec_…) werden nur einmal bei der Erstellung angezeigt — sicher aufbewahren. Keys lassen sich benennen, mit einem Ausgabelimit versehen und jederzeit widerrufen.
Authorization: Bearer hda_live_...
Keys werden gehasht gespeichert und sind ausschließlich an den eigenen Account gebunden — ein API-Key kann niemals Daten eines anderen Accounts lesen.
GET /v1/account meldet "mode": "sandbox_watermarked"). Die erste Zahlung entfernt die Wasserzeichen automatisch von allen zuvor generierten Produkten.Ausgabelimits: Jeder Key hat ein optionales spend_cap_cents (Standard: unbegrenzt). Ist es erreicht, schlägt die Task-Erstellung mit spend_cap_exceeded (403) fehl.
Antwort-Envelope
{ "status": 200, "code": 200, "message": "", "data": { … } }
Fehler enthalten zusätzlich einen error_code für den programmatischen Abgleich. Transportfehler vs. Task-Fehler: HTTP 4xx/5xx bedeutet, dass die Anfrage fehlgeschlagen ist. Ein Task, der während der Generierung scheitert, ist kein HTTP-Fehler — das Polling liefert 200 mit status: "failed" und einem error-Feld, und es wird nichts berechnet.
Schnellstart
# 1. Task erstellen
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. Alle 15–30s pollen bis zum Endstatus
curl -H "Authorization: Bearer $HEDAAI_API_KEY" https://hedaai.com/api/v1/tasks/3f8a…
# → data.status = "succeeded", data.product_id = "9c1b…"
# 3. Fertiges Produkt abrufen (12 Bild-URLs + Listing-Text)
curl -H "Authorization: Bearer $HEDAAI_API_KEY" https://hedaai.com/api/v1/products/9c1b…
POST/v1/tasks
Erstellt einen Generierungs-Task. Optionaler Header: Idempotency-Key (≤64 Zeichen, siehe unten).
| Feld | Typ | Pflicht | Hinweise |
|---|---|---|---|
product_name | string | ja | Kurzer Produktname. Starkes Grounding-Signal — möglichst konkret formulieren. |
images | string[1–8] | ja | Foto-URLs (öffentlich http/https, je ≤15MB) und/oder base64 / Data-URIs. Fotos aus mehreren Winkeln verbessern die Detailtreue. |
aspect_ratio | string | ja | 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9. Amazon-Hauptbilder verwenden 1:1. |
category | string | nein | Konkrete Kategorie, z. B. „Ersatzfilter für Staubsauger“. Empfohlen. |
brand_name | string | nein | Fließt in Brand-Story-Bilder und Listing-Text ein. |
key_features | string[≤10] | nein | Verkaufsargumente, die zwingend sichtbar sein müssen. |
specs | object | nein | {material, colorway, key_components[], usage_context, use_scenarios[], dimensions[], scale}. Empfohlen — die API hat keinen interaktiven Review-Schritt, das Grounding ergibt sich allein aus den übergebenen Daten. |
target_market | string | nein | amazon_us (Standard) · shopify · ebay |
copy_language | string | nein | Locale des Listing-Texts (en-US, de-DE, ja-JP, …). Standard ergibt sich aus dem Zielmarkt. |
aplus_format | string | nein | banner (16:9, Standard) · aplus_3_4 · aplus_9_16 · standard_aplus/premium (nur Amazon) |
no_human_models | bool | nein | true = keine Personen in irgendeinem Bild. |
supplementary_text | string ≤5000 | nein | Freitext-Spezifikationen / Handbuchauszüge, die die KI auswerten kann. |
callback_url | string | nein | Webhook für den Endstatus (Webhooks). |
Gibt ein Task-Objekt zurück:
{
"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}
Status-Lebenszyklus: queued → processing → succeeded | partial_failed | failed | canceled.
- succeeded — alle 12 Bilder fertig;
product_idgesetzt;cost_cents: 100berechnet. - partial_failed — einzelne Bilder sind fehlgeschlagen; das Produkt mit den erfolgreichen Bildern wird trotzdem gespeichert; keine Berechnung.
- failed / canceled — keine Berechnung;
errornennt den Grund.
Alle 15–30 Sekunden pollen. queue_position / eta_seconds sind befüllt, solange der Task in der Warteschlange steht.
POST/v1/tasks/{task_id}/cancel
Bricht einen Task ab. Kostenlos, solange er in der Warteschlange steht; bereits abgeschlossene Tasks bleiben unberührt (idempotent).
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–M8sind die 8 Hauptbilder,A1–A4die A+ Banner.url_2kerscheint bei zahlenden Accounts, sobald das asynchrone 2K-Upscaling abgeschlossen ist (nur Hauptbilder) — es kannsucceededum einige Minuten hinterherhinken.- Direkt nach
succeededkann eine Bildzeile kurzzeitig noch ausstehen — bei weniger als 12 Bildern nach ein paar Sekunden erneut abrufen. - URLs sind dauerhaft (ausgeliefert über unser CDN); Hotlinking und Kopieren sind beide erlaubt.
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 }
}
Idempotenz
Bei POST /v1/tasks einen Idempotency-Key-Header (≤64 Zeichen) mitschicken. Ein Retry mit demselben Key und demselben Body liefert den ursprünglichen Task zurück, statt ein Duplikat zu erstellen (und letztlich zu berechnen). Derselbe Key mit abweichendem Body liefert 409 idempotency_conflict. Für Agenten und Automatisierung dringend empfohlen — Netzwerk-Retries werden damit sicher gegen Doppelbelastung.
Webhooks
callback_url bei der Task-Erstellung setzen, um beim Endstatus ein POST zu erhalten. Events: task.succeeded, task.partial_failed, task.failed, task.canceled.
{ "id": "evt_…", "type": "task.succeeded", "created_at": "2026-07-17T08:11:35Z",
"data": { /* Task-Objekt — gleiche Struktur wie GET /v1/tasks/{id} */ } }
Signaturen folgen der Spezifikation Standard Webhooks — Header webhook-id, webhook-timestamp, webhook-signature: v1,<base64>. Prüfung mit dem webhook_secret des Keys:
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,"))
Zügig mit einem beliebigen 2xx antworten (aufwendige Arbeit asynchron erledigen). Zustellung: ein sofortiger Versuch, Retries nach 3s / 6s / 12s, danach als fehlgeschlagen markiert (Polling funktioniert weiterhin). Veraltete Timestamps (>5 min) ablehnen und per id deduplizieren. callback_url muss ein öffentlicher http(s)-Endpoint sein — private/interne Adressen werden abgelehnt.
Rate-Limits & Nebenläufigkeit
| Limit | Wert | Bei Überschreitung |
|---|---|---|
| Anfragen pro Key | 120 / min (alle Endpoints) | 429 rate_limited — Header RateLimit-Limit / -Remaining / -Reset prüfen |
| Laufende Tasks pro Key | 2 (queued + processing) | 429 concurrency_limit — warten, bis ein Task fertig ist |
| Plattform-API-Kapazität | dynamisch | 429 api_capacity — in einigen Minuten erneut versuchen |
Die Generierung ist rechenintensiv (13–20 KI-Bildaufrufe pro Task), daher wird der Durchsatz über die Slots laufender Tasks geregelt und nicht über die Request-Rate. Mehr Nebenläufigkeit nötig? Kontakt aufnehmen.
Fehler
| error_code | HTTP | Bedeutung |
|---|---|---|
bad_request | 400 | Ungültige Parameter — die Meldung benennt das betroffene Feld (z. B. images[2]: image download failed with HTTP 403). |
unauthorized | 401 | API-Key fehlt, ist ungültig oder wurde widerrufen. |
insufficient_credits | 402 | Guthaben zu gering; data.balance_cents ist enthalten. |
spend_cap_exceeded | 403 | Das Ausgabelimit dieses Keys ist ausgeschöpft. |
account_disabled / email_not_verified / email_bounced | 403 | Sperren auf Account-Ebene. |
not_found | 404 | Task/Produkt existiert nicht oder gehört zu einem anderen Account. |
idempotency_conflict | 409 | Gleicher Idempotency-Key, anderer Body. |
concurrency_limit / api_capacity / rate_limited | 429 | Siehe Limits. |
generation_failed / internal_error | 500 | Serverseitiger Fehler; ein Retry mit Idempotency-Key ist unbedenklich. |
Codebeispiele
Der komplette Ablauf — Task erstellen, bis zum Endstatus pollen, fertiges Produkt abrufen — in der Sprache der Wahl.
API=https://hedaai.com/api/v1
# 1. Task erstellen
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. Pollen bis zum Endstatus
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. Bilder + Listing-Text abrufen
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 erstellen
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. Pollen bis zum Endstatus
while task["status"] in ("queued", "processing"):
time.sleep(20)
task = requests.get(f"{API}/tasks/{task['task_id']}", headers=H).json()["data"]
# 3. Bilder + Listing-Text abrufen
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. Task erstellen
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. Pollen bis zum Endstatus
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. Bilder + Listing-Text abrufen
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. Task erstellen
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. Pollen bis zum Endstatus
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. Bilder + Listing-Text abrufen
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.*; // jede JSON-Bibliothek funktioniert
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. Task erstellen
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. Pollen bis zum Endstatus
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. Bilder + Listing-Text abrufen
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 erstellen
$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. Pollen bis zum Endstatus
while (in_array($task["status"], ["queued", "processing"])) {
sleep(20);
$task = call("GET", "$api/tasks/{$task['task_id']}", $headers);
}
// 3. Bilder + Listing-Text abrufen
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-Server (für KI-Agenten)
HedaAI stellt einen gehosteten Model Context Protocol-Server bereit, damit Agenten Produktbilder direkt generieren können:
- Endpoint:
https://hedaai.com/api/v1/mcp(Streamable HTTP, zustandslos) - Auth: derselbe Header
Authorization: Bearer hda_live_… - Tools:
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_..." }
}
}
}
Die Generierung ist asynchron: Agenten rufen create_product_shoot auf (optional mit idempotency_key), pollen alle 30–60s get_task bis zum Endstatus und holen dann per get_product die Bild-URLs und den Listing-Text. Clients, die OAuth voraussetzen (z. B. claude.ai Custom Connectors), werden noch nicht unterstützt — API-Key-fähige Clients wie Claude Code, Cursor oder Agent-SDKs verwenden.
Preise
| Position | Preis |
|---|---|
| Produkt-Shooting — 12 Bilder + Listing-Text | $1.00, nur bei Erfolg berechnet |
| Startguthaben | $2.00 (≈ 2 kostenlose Tasks, mit Wasserzeichen bis zur ersten Zahlung) |
| Guthaben aufladen | $10–$1000 auf hedaai.com; ≥$50 +5% Bonus, ≥$100 +10% |
Guthaben verfällt nie. Kein Abo. Der aktuelle Preis ist jederzeit über GET /v1/account abrufbar (price_per_task_cents).