aisplice

API-Referenz

Bilder: asynchrone Tasks

Modelle für diesen Endpunkt (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
In der Workbench ausprobieren
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Asynchrone Bildgenerierung — die Route, die jedes Bildmodell im Katalog nutzt. Das Einreichen gibt eine task_id zurück; fragen Sie den Status-Endpunkt ab und lesen Sie dann die dauerhaften Ergebnis-URLs über /content — oder registrieren Sie einen Webhook und sparen Sie sich das Abfragen.

#Anfrageparameter

  • modelstringerforderlich

    Eine asynchrone Bildmodell-ID, z. B. gpt-image-2. Rein synchrone Modelle lehnen diesen Endpunkt ab.

  • promptstringerforderlich

    Was gezeichnet werden soll.

  • sizestringoptional

    Seitenverhältnis-Vorgabe wie "16:9" — das nehmen die meisten Bildmodelle; die genauen Werte stehen auf der Modellkarte. Manche ältere Modelle akzeptieren auch WIDTHxHEIGHT.

  • resolutionstringoptional

    Auflösungsstufe der Ausgabe wie "1K", "2K" oder "4K", sofern die Modellkarte sie aufführt — ebenfalls eine Dimension der Preisstufe.

  • qualitystringoptional

    Qualitätsstufe des Anbieters (z. B. standard / hd) — ebenfalls eine Dimension der Preisstufe.

  • nintegeroptional

    Anzahl der Bilder (die Abrechnung multipliziert pro Bild).

  • imagesarrayoptional

    Referenzbilder zum Bearbeiten oder als Vorlage, als URLs oder Data-URIs. Wie viele ein Modell annimmt, steht auf seiner Modellkarte.

  • maskstringoptional

    Malt einen Bereich des ersten Referenzbilds neu — siehe „Einen Teil eines Bildes bearbeiten“ unten. Nur Modelle, deren Modellkarte mask aufführt, nehmen es an; mask_url wird als dasselbe Feld akzeptiert.

  • webhook_urlstringoptional

    HTTPS-URL, die aufgerufen wird, sobald der Task einen Endzustand erreicht — den Callback-Vertrag beschreibt der Video-Leitfaden.

  • webhook_secretstringoptional

    Wenn gesetzt, enthalten Zustellungen X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Parameter unterscheiden sich je nach Modell

Welche Felder und Werte ein Modell annimmt, steht auf seiner Modellkarte. gpt-image-2.5-ext erwartet size als Seitenverhältnis plus resolution; eine Pixelgröße wie 2560x1088 wird auf das nächstliegende Seitenverhältnis und die nächstliegende Auflösung abgebildet (21:9 bei 2K). background lässt sich dort nicht steuern: "auto" wird ignoriert, andere Werte werden abgelehnt. Es erzeugt ein Bild pro Anfrage und bietet keine Wahl bei version: Lassen Sie version weg oder senden Sie "flare".

Feldnamen können je nach Modellfamilie abweichen

Task-Status-Payloads spiegeln wider, was der Upstream-Anbieter meldet; maßgeblich sind Ihre tatsächlichen Antworten. Verlassen Sie sich auf task_id, status und den /content-Endpunkt, die anbieterübergreifend stabil sind.

#Einen Teil eines Bildes bearbeiten

Schicken Sie das Bild in images und dazu eine mask: Nur der maskierte Bereich wird neu gezeichnet, der Rest des Bildes bleibt, wie er ist. Beschreiben Sie in prompt, was dort erscheinen soll. Derzeit nehmen gpt-image-2.5-flare und gpt-image-2.5-sunburst eine Maske an; die Modellkarte zeigt sie als Feld mask.

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

So erstellen Sie die Maske

Ein PNG mit Alphakanal: Vollständig transparente Pixel markieren den Bereich, der neu gezeichnet wird, der Rest bleibt erhalten. Es muss genau die Pixelgröße des ersten Referenzbilds haben (nicht die der Ausgabe) und unter 4 MB liegen. Eine Maske pro Anfrage; bei mehreren Referenzbildern gilt sie für das erste. Lassen Sie bei den gpt-image-2.5-Modellen size weg, damit das Ergebnis das Seitenverhältnis des Bildes behält.
  • 400 invalid_requestmask wurde ohne Referenzbild gesendet oder an ein Modell, das keine Maske annimmt (gpt-image-2.5-ext antwortet mit "mask is not supported on Ext").

Vollständige Fehlercode-Tabelle →

#Zugehörige Fehler

  • 404 not_foundUnbekannter Pfad, unbekannter Modellname oder eine abgelaufene bzw. fremde task_id.
  • 401Ungültiges oder fehlendes Bearer-Token. Auf diesem Pfad gibt es kein error.code — werten Sie den Status aus.
  • 402 insufficient_user_quotaDas Wallet-Guthaben deckt die vorab reservierte Schätzung nicht.
  • 429Drosselung pro Schlüssel. Leerer Body; warten Sie Retry-After ab. Ein 429, das insufficient_user_quota enthält, ist dagegen ein tägliches Ausgabenlimit.
  • 503 model_not_foundUnbekanntes Modell, oder derzeit bedient es kein funktionsfähiger Kanal.

Vollständige Fehlercode-Tabelle →

#Beispielanfrage

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#Antwort

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

Immer noch nicht gelöst?

Senden Sie uns die Anfrage-ID oder die Fehlermeldung, und wir sehen uns das an.

ZurückMessages (Anthropic-Format)WeiterVideos