aisplice

Référence API

Images : tâches asynchrones

Modèles sur cet endpoint (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
L'essayer dans le Workbench
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Génération d'images asynchrone — la route utilisée par tous les modèles d'image du catalogue. La soumission renvoie un task_id ; interrogez l'endpoint de statut, puis lisez les URL de résultat persistantes depuis /content — ou enregistrez un webhook et passez-vous de l'interrogation.

#Paramètres de la requête

  • modelstringobligatoire

    Un ID de modèle d'image asynchrone, par ex. gpt-image-2. Les modèles uniquement synchrones rejettent cet endpoint.

  • promptstringobligatoire

    Ce qu'il faut dessiner.

  • sizestringfacultatif

    Format prédéfini comme "16:9" — ce qu'attendent la plupart des modèles d'image ; les valeurs exactes figurent sur la fiche du modèle. Certains modèles plus anciens acceptent aussi WIDTHxHEIGHT.

  • resolutionstringfacultatif

    Palier de résolution de sortie comme "1K", "2K" ou "4K", si la fiche du modèle le mentionne — également une dimension de palier.

  • qualitystringfacultatif

    Niveau de qualité du fournisseur (par ex. standard / hd) — également une dimension de palier.

  • nintegerfacultatif

    Nombre d'images (la facturation est multipliée par image).

  • imagesarrayfacultatif

    Images de référence à modifier ou à suivre, sous forme d’URL ou de data URI. La fiche du modèle indique combien chaque modèle en accepte.

  • maskstringfacultatif

    Redessine une zone de la première image de référence — voir « Modifier une partie d’une image » plus bas. Seuls les modèles dont la fiche indique mask l’acceptent ; mask_url est accepté comme le même champ.

  • webhook_urlstringfacultatif

    URL HTTPS appelée dès que la tâche atteint un état final — voir le guide vidéo pour le contrat de callback.

  • webhook_secretstringfacultatif

    Si défini, les envois portent X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Les paramètres varient selon le modèle

Consultez la fiche du modèle pour les champs et valeurs que chaque modèle accepte. gpt-image-2.5-ext attend size sous forme de format plus resolution ; une taille en pixels comme 2560x1088 est ramenée au format et à la résolution les plus proches (21:9 en 2K). background n'y est pas réglable : "auto" est ignoré, les autres valeurs sont rejetées. Il produit une image par requête et ne propose pas de choix de version : omettez version ou envoyez "flare".

Les noms de champs peuvent varier selon la famille de modèles

Les réponses de statut de tâche reflètent ce que rapporte le fournisseur en amont ; considérez vos réponses réelles comme faisant foi et appuyez-vous sur task_id, status et l'endpoint /content, qui sont stables d'un fournisseur à l'autre.

#Modifier une partie d’une image

Envoyez l’image dans images et un mask : seule la zone masquée est redessinée, le reste de l’image ne change pas. Décrivez dans prompt ce qui doit y apparaître. Aujourd’hui, gpt-image-2.5-flare et gpt-image-2.5-sunburst acceptent un masque ; la fiche du modèle l’affiche comme champ 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"
  }'

Comment créer le masque

Un PNG avec canal alpha : les pixels entièrement transparents marquent la zone à redessiner, le reste est conservé. Il doit avoir exactement la taille en pixels de la première image de référence (pas celle de la sortie) et peser moins de 4 Mo. Un seul masque par requête ; avec plusieurs images de référence, il s’applique à la première. Sur les modèles gpt-image-2.5, omettez size pour que le résultat garde le format de l’image.
  • 400 invalid_requestmask a été envoyé sans image de référence, ou à un modèle qui n’accepte pas de masque (gpt-image-2.5-ext répond "mask is not supported on Ext").

Table complète des codes d'erreur →

#Erreurs associées

  • 404 not_foundChemin inconnu, nom de modèle inconnu, ou task_id expiré / appartenant à un autre compte.
  • 401Jeton bearer invalide ou manquant. Pas de error.code sur ce chemin — basez-vous sur le statut.
  • 402 insufficient_user_quotaLe solde du portefeuille ne couvre pas l'estimation préréservée.
  • 429Limitation par clé. Corps vide ; attendez Retry-After. Un 429 qui contient insufficient_user_quota correspond en revanche à un plafond de dépenses quotidien.
  • 503 model_not_foundModèle inconnu, ou aucun canal opérationnel ne le sert actuellement.

Table complète des codes d'erreur →

#Exemple de requête

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

#Réponse

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://…"}]}

Toujours bloqué ?

Envoyez-nous l'ID de requête ou le message d'erreur, et nous examinerons le problème.

PrécédentMessages (format Anthropic)SuivantVidéos