Édition d'images
Modifiez des images, faites de l'inpainting par masque et créez des variations avec l'API Images.
Vue d'ensemble
L'API Images modifie une image existante de trois façons : édition de l'image entière, retouche par masque (inpainting) et variations. Chaque mode reçoit son image source (et un masque optionnel) sous forme de ressource téléversée — il n'y a ni voie URL ni voie intégrée.
Avertissement
/v1/images/edits et /v1/images/variations n'acceptent que application/json. L'ancien téléversement de fichier multipart/form-data a été supprimé — envoyer du multipart retourne 415 legacy_multipart_removed. Que l'image fasse quelques KB ou 25 MB, la source et le masque doivent d'abord passer par un téléversement pré-signé, puis vous soumettez du JSON avec image_upload_id / mask_upload_id.
Trois modes
| Mode | Point de terminaison | Requis | Effet |
|---|---|---|---|
| Édition de l'image entière | POST /v1/images/edits | model, prompt, image_upload_id | Modifier toute l'image selon le prompt |
| Retouche par masque | POST /v1/images/edits | ci-dessus + mask_upload_id | Ne modifier que la région masquée |
| Variation | POST /v1/images/variations | model, image_upload_id (sans prompt) | Générer des variantes du même style |
Transmettre mask_upload_id fait automatiquement passer une édition en mode inpainting — aucun indicateur supplémentaire n'est nécessaire.
Modifier une image
D'abord, pré-signez et téléversez la source avec purpose=image_edit_source (et, pour l'inpainting, le masque avec purpose=image_edit_mask). Puis soumettez le JSON :
| 1 | curl https://api.alltoken.ai/v1/images/edits -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "prompt": "Change the background to a sunset", |
| 4 | "image_upload_id": "upl_source...", |
| 5 | "mask_upload_id": "upl_mask...", |
| 6 | "size": "1024x1024", |
| 7 | "output_format": "png" |
| 8 | }' |
Champs optionnels courants : size, quality, output_format, output_compression, background, moderation, n, user. Voir la référence de l'API Image pour la liste complète.
Créer des variations
Les variations ne nécessitent qu'une source (téléversée avec purpose=image_variation_source) — sans prompt :
| 1 | curl https://api.alltoken.ai/v1/images/variations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "image_upload_id": "upl_source...", |
| 4 | "n": 2 |
| 5 | }' |
Champs optionnels : size, n, output_compression, user.
Obtenir le résultat
La création retourne 202 + { id, status: "queued", ... }. Les trois modes interrogent le même point de terminaison :
$curl https://api.alltoken.ai/v1/images/generations/{id} -H "Authorization: Bearer $ALLTOKEN_API_KEY"Pendant queued / processing, la réponse contient next_poll_after_ms — utilisez-le pour cadencer la prochaine interrogation. Une fois completed, chaque élément data[] contient b64_json, r2_url, r2_url_expires_at, mime_type et revised_prompt.
Avertissement
b64_json n'est délivré qu'une seule fois — seul le premier GET completed le retourne, alors écrivez-le sur disque immédiatement. Préférez r2_url (valable 30 jours, multi-appareils) et considérez b64_json comme un recours pour la première récupération. Une fois r2_url expiré, le GET retourne 410 image_expired. Il n'existe pas de point de terminaison « list images » — enregistrez vous-même les résultats par task_id.
Édition par lots
Une requête traite une seule image source (plus un masque optionnel). Pour modifier N images, exécutez N flux indépendants en trois étapes — chacun avec sa propre séquence pré-signature → PUT → création → interrogation. Vous pouvez les exécuter en parallèle ; surveillez deux limites :
- 100 téléversements en attente — ne pré-signez pas des centaines d'
upload_idpour les laisser inutilisés. - 2 GiB par jour UTC — environ 80 fichiers de 25 MiB atteignent le plafond.
Recommandé : maintenez 5 à 10 voies en parallèle, chacune exécutant une séquence complète pré-signature → PUT → création → interrogation avant de passer à l'image suivante. Le nombre d'éléments en attente reste faible et vous n'atteignez jamais le quota. Voir Téléversement de médias pour les détails des quotas.