curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
Grok Imagine 2.0 Ext
Grok Imagine 2.0 Ext Bildgenerierung
- Asynchrone Text-zu-Bild-Generierung; Ergebnis per task_id abfragen
- 1–12 Bilder pro Anfrage; Abrechnung pro erfolgreich geliefertem Bild ($0.08/Stück)
- Nur URL-Ausgabe; kein Bild-zu-Bild / Streaming
- Bild-URLs sind 72 Stunden gültig
POST
/
v1
/
images
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
Text-zu-Bild · asynchrone Aufgaben. Senden Sie
Modellname fest:
POST /v1/images/generations und pollen Sie anschließend Aufgabenstatus abrufen.Modellname fest:
grok-imagine-2.0-ext. Nicht unterstützt: Referenzbilder, stream sowie response_format-Werte außer url.Informationen zu Objektebenen und der Bearbeitung ausgewählter Bereiche finden Sie unter Ebenen- und Bereichsbearbeitung.
Legen Sie API-Keys nicht in Browser-Bundles ab (
VITE_* / NEXT_PUBLIC_*, LocalStorage usw.). Rufen Sie aus dem Browser idealerweise nur Ihr eigenes BFF auf; der APIMart-Key bleibt auf dem Server.curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
Fähigkeiten und Grenzen
| Dimension | Vertrag |
|---|---|
| Modell | Fest grok-imagine-2.0-ext |
| Fähigkeit | Nur Text-zu-Bild |
| Modus | Asynchrone Aufgabe |
Anzahl n | 1–12, Standard 1 |
size | 7 Seitenverhältnisse + 5 Pixel-Aliase (siehe unten) |
| Ausgabe | Nur response_format=url (auch Standard) |
| Qualität | Öffentliches Feld resolution; verifizierter Wert quality |
| Nicht unterstützt | Bild-zu-Bild, stream=true, öffentliches quality, style, b64_json / base64 |
| Abrechnung | Fester Stückpreis; Abrechnung nach erfolgreich gelieferten Bildern |
Authentifizierung und empfohlene Header
string
erforderlich
Bearer-Token. Schlüssel auf der API-Key-Seite erstellen.
Authorization: Bearer YOUR_API_KEY
| Header | Hinweise |
|---|---|
Content-Type | application/json (Absenden) |
Accept | application/json |
Idempotency-Key | Dringend empfohlen. Neue UUID pro vom Nutzer bestätigter Generierung; Netzwerk-Retries müssen denselben Key und Body wiederverwenden |
X-APIMart-Response-Version | Bevorzugt 2026-07-27 für eine stabile Submit-Struktur (data.id) |
Anfrageparameter
string
erforderlich
Fester Wert:
grok-imagine-2.0-extboolean
Standard:"false"
Legt fest, ob der Inhalt vor dem Absenden des Bildauftrags moderiert wird.
true: Prompts und Eingabebilder mitomni-moderation-latestprüfenfalseoder nicht angegeben: keine Moderationsanfrage und damit keine zusätzlichen Moderationskosten oder Verzögerung (Standard)
string
erforderlich
Prompt. Nach Trim darf er nicht leer sein. Vor dem Absenden trimmen.
integer
Standard:"1"
Bildanzahl:
1–12. Explizites 0 führt zu einem Fehler. Weglassen → 1.string
Seitenverhältnis. Bevorzugen Sie Verhältnis-Strings (UI sollte nur Verhältnisse anzeigen):
Pixel-Aliase:
size | Ausrichtung | Typische Nutzung |
|---|---|---|
1:1 | Quadrat | Produkt, Avatar |
2:3 | Hochformat | Poster, Ganzkörper |
3:2 | Querformat | Foto, breite Szene |
3:4 | Hochformat | E-Commerce, Personen |
4:3 | Querformat | Anzeigebilder |
9:16 | Vertikal | Story / Kurzvideo-Cover |
16:9 | Breitbild | Banner, Video-Cover |
1024x1024 (1:1), 1024x1792 (2:3), 1792x1024 (3:2), 720x1280 (9:16), 1280x720 (16:9).Werte außerhalb der Whitelist liefern 400 invalid_size (z. B. 1:2, 2:1, 4:5, auto).Die tatsächlichen Pixel zu einem Verhältnis können von der Alias-Tabelle abweichen (z. B. kann
1:1 1408×1408 zurückgeben). Vertrauen Sie dem zurückgegebenen Bild; leiten Sie size nicht aus gemessenen Pixeln um.string
Qualitätsmodus-Feld. Verifizierter Wert:
quality.- Weglassen (Modell ist standardmäßig im Qualitätsmodus), oder
- Explizit
resolution: "quality"senden
1K / 2K / 4K-Pixel-Tier; Bildausschnitt und Verhältnis steuert size.Senden Sie kein öffentliches Feld
quality — Sie erhalten 400 invalid_quality. Verwenden Sie resolution.string
Standard:"url"
Nur
url ist erlaubt. Darf weggelassen werden. b64_json / base64 → 400 invalid_response_format.string
Optionale öffentliche HTTPS-Basis-URL. Bei Endstatus sendet die Plattform einen POST an
{webhook}/callback. Nur serverseitig — siehe Webhook.Nicht unterstützte Parameter
| Parameter | Verhalten |
|---|---|
quality | 400 invalid_quality → resolution verwenden |
style | 400 invalid_style |
image_urls / image_with_roles | 400 invalid_image_input |
stream: true | 400 invalid_stream |
response_format: "b64_json" / "base64" | 400 invalid_response_format |
Anfragebeispiele
Minimal
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo"
}
Empfohlen
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}
Submit-Antwort
Bevorzugen SieX-APIMart-Response-Version: 2026-07-27. Erfolg ist HTTP 202; die Task-ID steht in data.id (verlassen Sie sich nicht auf das Legacy-Format data[0].task_id).
Speichern Sie:
data.idzum Pollenrequest_idfür Gateway-Debugging- den
Idempotency-Keyfür sichere Retries bei unklarem Ergebnis - die originalen Anfrageparameter für UI / Support
Idempotenz und sichere Retries
Bildgenerierung ist kostenpflichtig — dringend empfohlen istIdempotency-Key (1–191 druckbare ASCII-Zeichen; UUID ist am einfachsten; Aufbewahrung ca. 24 Stunden).
| Szenario | Verhalten | Aktion |
|---|---|---|
| Gleicher Key + gleicher Body bereits erledigt | Replay; Header Idempotency-Replayed: true | Dieselbe Task-ID verwenden |
| Gleicher Key noch in Bearbeitung | 409 idempotency_in_progress + Retry-After | Warten, mit gleichem Key und Body erneut versuchen |
| Gleicher Key, anderer Body | 409 idempotency_key_reused | Neuer logischer Job braucht einen neuen Key |
| Ergebnis unbestimmt | 409 idempotency_result_indeterminate | Keinen neuen Key erzeugen; mit dem alten untersuchen |
Aufgaben pollen
GET /v1/tasks/{task_id}?language=en
Authorization: Bearer YOUR_API_KEY
Accept: application/json
language: zh / en / ko / ja (nur Lokalisierung von Fehlermeldungen). Siehe Aufgabenstatus abrufen.
Statuswerte
status | Endstatus | Behandlung |
|---|---|---|
pending / processing | Nein | Weiter pollen (result kann fehlen — kein Fehler) |
completed | Ja | result.images parsen |
failed | Ja | error.message anzeigen; cost ist 0 (Vorabbuchung erstattet) |
unknown | Nein | Kurze Retries; bei Anhalten Support mit Task-ID kontaktieren |
429 den Header Retry-After beachten. Aufgaben werden standardmäßig ca. 3 Tage aufbewahrt — Task-ID behalten, falls der Client timeoutet.
Beispiel für abgeschlossene Aufgabe
{
"code": 200,
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"status": "completed",
"progress": 100,
"created": 1786419262,
"completed": 1786419275,
"actual_time": 13,
"estimated_time": 100,
"cost": 0.08,
"credits_cost": 0.8,
"result": {
"images": [
{
"expires_at": 1786505675,
"url": [
"https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
],
"image_ids": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}
]
}
}
}
url und image_ids parsen
result.images[]
├─ url[] ← maßgebliches Anzeige-/Download-Feld (Array)
├─ image_ids[] ← optionale opake IDs
└─ expires_at ← Unix-Sekunden; für JS Date mit 1000 multiplizieren
- Für die Anzeige
url[]verwenden; bein>1alle Einträge durchlaufen - Nur indexweise paaren, wenn
image_ids.length === url.length - Fehlende
image_idserlauben weiterhin die Anzeige - Links gelten 72 Stunden — zeitnah herunterladen; zusätzlich
expires_atvertrauen
Abrechnung
Grundpreis $0.08 pro Bild (erfolgreiche Lieferungen):n | Geschätzter Grundbetrag |
|---|---|
| 1 | $0.08 |
| 4 | $0.32 |
| 8 | $0.64 |
| 12 | $0.96 |
- UI vor dem Absenden sollte „Schätzung“ anzeigen; finaler USD-Betrag ist
data.cost data.credits_costist die Credits-Sicht (aktuell ca. USD × 10)- Vorabbuchung nach angeforderter Anzahl; Abrechnung nach erfolgreicher Anzahl (Teilerstattung bei Teilfehlern)
- Vollständiger Fehler:
cost=0, Vorabbuchung erstattet - Keine Preisschlüssel aus
resolutionableiten; dieses Modell hat einen flachen Stückpreis
Webhook (optional)
{
"webhook": "https://your-service.example.com/apimart"
}
- Geben Sie eine Basis-URL an; die Plattform ruft
{base}/callbackauf - Muss öffentlich erreichbar sein und SSRF-Prüfungen bestehen
- Ist
webhook_secretgesetzt, lautet die Signaturhex(HMAC-SHA256(secret, raw_body))über die Rohbytes - Callback-Body entspricht dem
datader Aufgabenabfrage (ohne zusätzlichen{code,data}-Wrapper) - Behalten Sie trotzdem niedrigfrequentes Pollen als Fallback
Häufige Fehler
| HTTP | error.code | Ursache | Aktion |
|---|---|---|---|
| 400 | invalid_request | Leerer Prompt / ungültiges JSON | Eingabe validieren |
| 400 | invalid_n | n außerhalb 1–12 | Anzahl begrenzen |
| 400 | invalid_size | Size nicht auf Whitelist | Feste Select-Optionen |
| 400 | invalid_response_format | Nicht url | Korrigieren oder weglassen |
| 400 | invalid_quality | Öffentliches quality gesendet | resolution verwenden |
| 400 | invalid_style | style gesendet | Entfernen |
| 400 | invalid_image_input | Referenzbilder | Anderes Modell wählen |
| 400 | invalid_stream | stream=true | Entfernen |
| 400 | invalid_idempotency_key | Ungültiger Key | UUID verwenden |
| 401 | Auth-Fehler | Ungültiger Key | Server-Credentials prüfen |
| 402 | Zahlung erforderlich | Guthaben zu niedrig | Aufladen |
| 409 | idempotency_* | Idempotenz-Konflikt | Siehe Tabelle oben |
| 429 | Rate Limit | Zu schnell | Retry-After beachten |
| 5xx | Serverfehler | — | Idempotency-Key behalten; nicht blind rotieren |
error.message verwenden. Authentifizierungs-Internals nicht an Endnutzer weitergeben.
Unterschiede zu 1.5 (Kurzüberblick)
| Punkt | Grok Imagine 1.5 | 2.0 Ext |
|---|---|---|
| Modell | grok-imagine-1.5-apimart usw. | grok-imagine-2.0-ext |
| Bild-zu-Bild | Unterstützt (siehe 1.5-Docs) | Nicht unterstützt |
| Anzahl | Siehe 1.5-Docs | 1–12 |
| Qualitätsfeld | Siehe 1.5-Docs | resolution (quality); nie öffentliches quality |
| Ausgabe | Siehe 1.5-Docs | Nur URL |
| URL-TTL | Siehe 1.5-Docs (oft 24 h) | 72 Stunden |
| Stückpreis | Siehe 1.5-Docs | $0.08 / Bild |