Bilder erzeugen

POST /v1/images/generations

Erzeugt Bilder. Standardmäßig synchron – der Aufruf wartet, bis das Bild fertig ist, und antwortet in derselben Form wie der OpenAI-Endpunkt images/generations, sodass OpenAI-SDK und Relay-Gateways direkt funktionieren. Mit async: true bekommst du sofort eine Auftrags-id und holst das Ergebnis per GET /v1/tasks/{id}. Bei n größer 1 entstehen n eigenständige Aufträge, die einzeln abgerechnet werden.

Parameter

Parameter	Typ	Beschreibung
prompt	string	Pflicht. Was gezeichnet werden soll
model	string	Modell-id aus /v1/models. Ohne Angabe das Standardmodell
n	integer	Anzahl Bilder 1–4. Standard 1
size	string	Seitenverhältnis 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4. Standard 1:1. Pixelangaben wie 1024x1024 oder 1792x1024 werden ebenfalls akzeptiert und auf das nächstliegende Verhältnis gerundet
quality	string	Qualität 1k \| 2k \| 4k. Standard 1k, wird von spec überschrieben. OpenAI-Schreibweisen gelten auch: standard / low / auto entsprechen 1k, medium / hd / high entsprechen 2k
spec	string	Stufenschlüssel aus specs[].key des Modells
reference_images	string[]	URLs von Referenzbildern. Was über max_reference_images hinausgeht, entfällt
async	boolean	Standard false – auf das Bild warten. true liefert sofort ein Auftragsobjekt; /v1/tasks/{id} dann selbst pollen

Unbekannte Werte lassen die Anfrage nicht scheitern, sondern fallen auf den Standard zurück – ein unbekanntes size rendert einfach in 1:1. Nur leerer prompt, gesperrte Inhalte, erreichte Kontingente oder fehlende Credits führen zum Fehler. response_format wird nicht unterstützt; Ergebnisse kommen immer als URL.

Anfrage (synchron)

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "eine regennasse Cyberpunk-Straße bei Nacht, Neonspiegelungen",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

Antwort (synchron)

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "eine regennasse Cyberpunk-Straße bei Nacht, Neonspiegelungen" }
  ],
  "id": "2608101909450810293847",
  "object": "image.generation",
  "model": "img-std-1",
  "status": "succeeded",
  "n": 1,
  "credits": 10,
  "tasks": [
    {
      "id": "2608101909450810293847",
      "status": "succeeded",
      "data": [{ "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "eine regennasse Cyberpunk-Straße bei Nacht, Neonspiegelungen" }]
    }
  ]
}

Feld	Beschreibung
created	Zeitstempel der Antwort
data	Ergebnisse, je mit url und revised_prompt. Bei n > 1 mehrere Einträge
id	Hauptauftrag (bei n > 1 der erste Teilauftrag)
status	succeeded – auch bei Teilerfolg; vergleiche die Länge von data selbst mit n
credits	Insgesamt abgezogene Credits
tasks	Alle Teilaufträge, jeweils mit eigenem error und Ergebnis

Ein synchroner Aufruf hält die Verbindung offen, pro Bild oft über 30 Sekunden – setze das Client-Timeout auf 300 Sekunden. Nach 300 Sekunden antwortet der Server mit 504 generation_timeout; der Auftrag läuft weiter und die Credits werden nicht erstattet, du holst das Bild später über /v1/tasks/{id} mit der id aus der Meldung. Schlagen alle Bilder fehl, kommt 502 generation_failed und die Credits werden automatisch erstattet.

Asynchroner Ablauf

Für Stapelverarbeitung, hohe Parallelität oder latenzempfindliche Aufrufer: Die Antwort kommt sofort, status ist queued und data leer.

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "eine regennasse Cyberpunk-Straße bei Nacht, Neonspiegelungen",
    "size": "16:9",
    "quality": "2k",
    "n": 1,
    "async": true
  }'

json

{
  "id": "2608101909450810293847",
  "object": "image.generation",
  "created": 1786000185,
  "model": "img-std-1",
  "status": "queued",
  "n": 1,
  "credits": 10,
  "tasks": [
    { "id": "2608101909450810293847", "status": "queued", "data": [] }
  ],
  "data": []
}

Bei n > 1 über tasks iterieren. Wer nur id pollt, verliert die übrigen Bilder stillschweigend.