JoyAI Image API

API-Dokumentation

Generieren und bearbeiten Sie Bilder über eine öffentliche API. Verwenden Sie joyai für anweisungsbasierte Bildbearbeitung oder gptimage2 für GPT Image 2 Text-zu-Bild und Bildbearbeitung.

API-Schlüssel verwalten Schnellstart

Überblick

Endpunkt

/api/v1/generate

Ein Endpunkt für unterstützte Bildmodelle. Verhalten über das model-Feld wählen.

Auth

Bearer API-Schlüssel

Dashboard-API-Schlüssel im Authorization-Header. Server-Schlüssel werden nie an Browser gesendet.

Async

Task-basierte Ergebnisse

Generierung liefert eine task ID. Status-Endpunkt für finale Bild-URLs abfragen.

Authentifizierung

Jede Anfrage benötigt einen API-Schlüssel im Authorization -Header. Schlüssel erstellen oder rotieren unter Dashboard > API Keys.

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Modelle und Credits

model	Am besten für	Bildeingabe erforderlich	Credits
`joyai`	Anweisungsbasierte Bildbearbeitung mit 1–3 Referenzbildern.	Ja, 1–3 Bild-URLs.	24 Credits pro Anfrage.
`gptimage2`	Text-zu-Bild und Bildbearbeitung mit GPT Image 2.	Optional. Bilder für Bearbeitungsmodus hinzufügen.	Text: 2/4/6 low, 12/24/36 medium, 44/88/132 high für 1k/2k/4k. Edit: 6/12/18 low, 12/24/36 medium, 44/88/132 high für 1k/2k/4k.

Schnellstart

Senden Sie eine Anfrage an POST /api/v1/generate. Die API gibt sofort eine task ID zurück; nutzen Sie GET /api/v1/status zum Abfragen bis Erfolg oder Fehler.

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

Erstellt eine Bildgenerierungs- oder -bearbeitungsaufgabe. Anfragekörper ist JSON.

Anfrageparameter

Name	Typ	Erforderlich	Beschreibung
`model`	string	Ja	joyai oder gptimage2 verwenden.
`prompt`	string	Ja	Anweisung in natürlicher Sprache. joyai bis 1500 Zeichen; gptimage2 bis 20000.
`images`	string[]	Erforderlich für joyai; optional für gptimage2	Bild-URLs. joyai akzeptiert 1–3 Bilder; gptimage2 wechselt bei Bildern in den Edit-Modus.
`size`	string	Optional für joyai	Ausgabegröße wie 10241024. Standard 10241024.
`quality`	string	Optional für gptimage2	low, medium oder high. Standard medium.
`resolution`	string	Optional für gptimage2	1k, 2k oder 4k. Standard 1k.
`aspect_ratio`	string	Optional für gptimage2	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 oder 21:9.
`output_format`	string	Optional für gptimage2	png, jpeg oder webp. Standard png.
`callback_url`	string	Optional	URL, die mit der Aufgabe für Callback-Workflows gespeichert werden kann.

JoyAI Edit Beispiel

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

GPT Image 2 Beispiel

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

Antwort

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

Status mit der task ID aus /api/v1/generate. abfragen. model ist optional; task IDs werden wenn möglich automatisch geroutet.

cURL

curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

Fehler

Fehler nutzen dasselbe Format wie Erfolgsantworten. Öffentliche Antworten zeigen keine internen Provider-, Worker- oder Routing-Details.

JSON

{
  "code": 400,
  "message": "prompt is required",
  "data": null
}

Status	Bedeutung
`400`	Fehlende oder ungültige Parameter.
`401`	Fehlender oder ungültiger API-Schlüssel.
`402`	Unzureichende Credits.
`500`	Generierungs- oder Serverfehler. Bei Wiederholung Support kontaktieren.