JoyAI Image API

Documentation API

Générez et éditez des images via une seule API publique. Utilisez joyai pour l'édition par instructions, ou gptimage2 pour le text-to-image et l'édition GPT Image 2.

Gérer les clés API Démarrage rapide

Aperçu

Endpoint

/api/v1/generate

Un endpoint pour les modèles d'image pris en charge. Comportement via le champ model.

Auth

Clés API Bearer

Clé API du tableau de bord dans l'en-tête Authorization. Les clés serveur ne sont jamais envoyées au navigateur.

Async

Résultats par tâche

La génération renvoie un task ID. Interrogez status pour les URL finales.

Authentification

Chaque requête nécessite une clé API dans l'en-tête Authorization . Créez ou renouvelez les clés depuis Tableau de bord > Clés API.

En-tête

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Modèles et crédits

model	Idéal pour	Image requise	Crédits
`joyai`	Édition par instructions avec 1 à 3 images de référence.	Oui, 1 à 3 URL d'images.	24 crédits par requête.
`gptimage2`	Text-to-image et édition avec GPT Image 2.	Optionnel. Ajoutez des images pour le mode édition.	Text: 2/4/6 low, 12/24/36 medium, 44/88/132 high pour 1k/2k/4k. Edit: 6/12/18 low, 12/24/36 medium, 44/88/132 high pour 1k/2k/4k.

Démarrage rapide

Envoyez une requête à POST /api/v1/generate. L'API renvoie immédiatement un task ID ; utilisez GET /api/v1/status pour interroger jusqu'à succès ou échec.

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

Crée une tâche de génération ou d'édition d'image. Corps JSON.

Paramètres de requête

Nom	Type	Requis	Description
`model`	string	Oui	Utilisez joyai ou gptimage2.
`prompt`	string	Oui	Instruction en langage naturel. joyai jusqu'à 1500 caractères ; gptimage2 jusqu'à 20000.
`images`	string[]	Requis pour joyai ; optionnel pour gptimage2	URL d'images. joyai accepte 1 à 3 ; gptimage2 passe en mode édition si images présentes.
`size`	string	Optionnel pour joyai	Taille de sortie comme 10241024. Par défaut 10241024.
`quality`	string	Optionnel pour gptimage2	low, medium ou high. Par défaut medium.
`resolution`	string	Optionnel pour gptimage2	1k, 2k ou 4k. Par défaut 1k.
`aspect_ratio`	string	Optionnel pour gptimage2	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 ou 21:9.
`output_format`	string	Optionnel pour gptimage2	png, jpeg ou webp. Par défaut png.
`callback_url`	string	Optionnel	URL stockable avec la tâche pour les workflows de callback.

Exemple JoyAI Edit

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"
  }'

Exemple GPT Image 2

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"
  }'

Réponse

JSON

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

GET /api/v1/status

Interrogez le statut avec le task ID de /api/v1/generate. Le paramètre model est optionnel ; routage automatique des task ID quand possible.

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"
  }
}

Erreurs

Les erreurs utilisent le même format que les réponses réussies. Aucun nom de fournisseur, worker ou routage interne dans les réponses publiques.

JSON

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

Statut	Signification
`400`	Paramètres manquants ou invalides.
`401`	Clé API manquante ou invalide.
`402`	Crédits insuffisants.
`500`	Erreur de service ou serveur. Contactez le support si cela se répète.