Maîtriser l'inpainting et l'outpainting avec l'API d'édition d'images GPT Image 2
Modèles cibles :
gpt-image-2,gpt-image-2-official
Endpoint d'inférence :https://api.toapis.com/v1/images/generations
Associé : Guide de l'API GPT Image 2 · Workflows 4K par format d'image · Miroir et proxy global · Référence officielle de l'inpainting
1. TL;DR et vue d'ensemble des performances
- Objectif : remplacer une zone d'une image existante (inpainting) ou étendre la toile vers un nouveau format d'image (outpainting) sans inventer une seconde API non documentée.
- Contrat : utilisez les ID de modèle qui existent au catalogue. Le
gpt-image-2exact accepteprompt,sizecomme ratio,resolutioncomme1k/2k/4ketreference_imagesen option. L'inpainting par masque est documenté surgpt-image-2-officialavecimage_urlsplusmask_url. - Ce qui n'est pas le contrat actuel : un ID de modèle nommé
gpt-image-2-edit, unPOST /v1/images/editsmultipart synchrone, ousize: "1024x1024". Ces formes viennent d'anciens brouillons et ne doivent pas être recopiées dans de nouveaux clients. - E/S : importez les images sources et les masques avec
POST /v1/uploads/images, puis passez l'URL publique renvoyée. Le base64 n'est pas accepté dansreference_images,image_urlsoumask_url. - Protocole asynchrone : l'appel de soumission renvoie un
idde tâche. InterrogezGET /v1/images/generations/{id}jusqu'au statutcompletedoufailed. Un timeout client ne prouve pas que la tâche a échoué.
2. La puissance de l'édition d'image programmatique
Générer une image fixe à partir d'un prompt texte n'est que la première étape. Les catalogues, publicités et design systems en production ont plus souvent besoin d'une révision ciblée : remplacer un produit, nettoyer un arrière-plan ou étirer un packshot carré en un hero large — tout en conservant l'éclairage et l'identité du sujet.
La famille GPT Image 2 actuelle de ToAPIs couvre ces travaux sur un seul chemin, POST /v1/images/generations, avec deux ID de modèle différents :
| Tâche | ID de modèle | Comment pointer la source | Masque ? |
|---|---|---|---|
| Édition guidée par prompt ou transfert de style | gpt-image-2 | reference_images (liste d'URL, maximum 14) | Non documenté sur cet ID |
| Inpainting au pixel près | gpt-image-2-official | image_urls (liste d'URL, maximum 16) | mask_url obligatoire avec la première image |
| Extension de toile (outpainting) | L'un ou l'autre ID | Passez l'original en référence et changez size vers le ratio cible | Aucun flag d'outpaint dédié |
image_urls est un alias rétrocompatible de reference_images sur le gpt-image-2 exact, normalisé par la passerelle. Les exemples de canal officiel de la référence de l'API utilisent image_urls avec mask_url. Utilisez les noms de champs de la référence correspondant à l'ID que vous appelez réellement.
Un masque d'inpainting utilisable est un PNG avec canal alpha. Ses dimensions en pixels doivent correspondre à la première image de référence. Les pixels transparents (alpha = 0) constituent la zone de régénération ; les pixels opaques doivent être préservés. Construisez le masque dans votre pipeline (par exemple avec Pillow), importez-le et envoyez uniquement l'URL.
L'outpainting est un workflow, pas un endpoint séparé. Si vous avez un packshot 1:1 et besoin d'une bannière 16:9, gardez l'original en référence, définissez size sur 16:9, choisissez un palier resolution explicite et demandez au modèle de conserver le sujet et d'étendre la scène. Une variante pratique consiste à composer l'original sur une toile transparente plus grande, à importer cette toile et à l'utiliser comme référence — toujours sur /v1/images/generations, toujours sans flag outpaint: true.

Figure 1 : une toile source et une zone de masque interne passent par la passerelle ToAPIs ; le chemin documenté reste POST /v1/images/generations, avec mask_url réservé à gpt-image-2-official.
size et resolution suivent le même contrat qu'en texte vers image : size est un ratio comme 1:1 ou 16:9, et resolution vaut 1k, 2k ou 4k. Le gpt-image-2 exact n'expose pas de champ quality dans le contrat actuel du playground ; quality (low / medium / high) apparaît sur gpt-image-2-official. Voir le guide des workflows 4K pour le tableau de pixels documenté.
3. Implémentation en production : cURL et Python
Les exemples internationaux de cette série utilisent https://api.toapis.com. La documentation officielle indique aux utilisateurs de Chine continentale d'utiliser https://toapis.cn. Conservez un seul origin par environnement. Les chemins, les ID de modèle et l'en-tête Bearer restent identiques.
Étape 1 : importer une image source (et un masque si nécessaire)
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@./product.png"
La réponse contient data.url. Répétez l'appel pour un masque PNG lorsque vous appelez gpt-image-2-official. N'insérez pas de base64 dans la requête de génération.
Étape 2 : édition guidée par prompt sur le gpt-image-2 exact
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": ["https://example.com/product.png"]
}'
Étape 3 : inpainting par masque sur gpt-image-2-official
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
"size": "1:1",
"resolution": "1k",
"quality": "medium",
"image_urls": ["https://example.com/photo.png"],
"mask_url": "https://example.com/mask.png"
}'
Étape 4 : helper Python pour soumettre et interroger
Alignez les noms de champs sur la référence de l'API de l'ID de modèle que vous appelez. L'extrait utilise le chemin de statut d'image documenté et les statuts completed / failed.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def upload_image(path: str) -> str:
with open(path, "rb") as handle:
res = requests.post(
f"{BASE}/v1/uploads/images",
headers=HEADERS,
files={"file": handle},
timeout=60,
)
res.raise_for_status()
url = res.json().get("data", {}).get("url")
if not url:
raise RuntimeError(f"Unexpected upload envelope: {res.text}")
return url
def dispatch_edit(payload: dict) -> str:
res = requests.post(
f"{BASE}/v1/images/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json=payload,
timeout=30,
)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_image_task(task_id: str, deadline_s: int = 180) -> str:
poll_url = f"{BASE}/v1/images/generations/{task_id}"
interval = 2.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(
f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
)
if __name__ == "__main__":
source = upload_image("product.png")
# Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
task_id = dispatch_edit(
{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
"size": "16:9",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": [source],
}
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
Pour exécuter l'inpainting par masque, importez un masque RGBA correspondant, passez model à gpt-image-2-official et envoyez image_urls plus mask_url. Stockez l'ID de modèle, size et resolution à côté de l'enregistrement de tâche, afin qu'un changement ultérieur de SKU soit une décision explicite.
4. Gestion des erreurs et matrice des statuts
Les catégories ci-dessous sont des points de départ pour le diagnostic, pas une garantie de codes d'erreur ToAPIs exacts. Une soumission HTTP réussie exige tout de même de lire le status de la tâche.
| Statut HTTP | Catégorie courante | Action recommandée |
|---|---|---|
400 | Champ invalide ou combinaison non prise en charge | Confirmez l'ID de modèle, que size est un ratio documenté, que resolution vaut 1k / 2k / 4k, que les URL sont publiques et qu'un masque (si utilisé) est un PNG de même taille avec canal alpha sur gpt-image-2-official |
401 | Clé d'API absente ou invalide | Faites tourner la clé dans le tableau de bord ToAPIs et confirmez l'en-tête Authorization |
429 | Limite de débit ou de concurrence | Respectez Retry-After lorsqu'il est présent ; appliquez un backoff avec jitter ; ne réessayez que si c'est sûr |
5xx ou timeout réseau | Problème temporaire de passerelle ou d'amont | Vérifiez le statut de la tâche avant de renvoyer ; utilisez une politique de nouvelle tentative bornée |
5. Tarifs et ROI FinOps
- Ne réutilisez pas de prix unitaires de brouillons de planification comme une paire plate
$0.024/$0.048« standard vs HD ». Ces chiffres sont obsolètes face au catalogue actuel, qui tarifie par ID de modèle et, pour la comparaison standard de la landing GPT Image 2, par palier de résolution. - Le guide du modèle GPT Image 2 montre actuellement une comparaison sur la landing ToAPIs de
$0.015/$0.020/$0.025par image en1K/2K/4Kpour legpt-image-2standard. Traitez-la comme une comparaison publiée, pas comme une facture contractuelle. Les SKU de canal officiel et les remises de compte peuvent différer ; confirmez le tarif applicable à l'ID exact que vous appelez. - Le routage (
api.toapis.comversustoapis.cn) est un choix d'URL de base, pas une remise documentée. Les gains FinOps viennent des brouillons en1k, de l'évitement des soumissions en double après un timeout client et du choix de la bonne SKU (gpt-image-2versusgpt-image-2-official) plutôt que de la supposition d'un modèle « édition » moins cher. - Pour le contexte, consultez l'article sur les tarifs de GPT Image 2, puis vérifiez chaque chiffre au catalogue en direct avant de l'inscrire dans une prévision.
6. Questions fréquentes
Voir le bloc FAQ du frontmatter. En résumé : le gpt-image-2 exact ne documente ni mask_url ni /v1/images/edits ; l'inpainting par masque est documenté sur gpt-image-2-official ; les masques doivent être des PNG RGBA de même taille servis comme URL ; l'outpainting est un changement de size plus une image de référence ; la facturation doit être confirmée sur le compte pour l'ID de modèle exact.
7. Liste d'actions
- Créez une clé sur le portail développeur ToAPIs.
- Définissez une URL de base par environnement (
https://api.toapis.comou, si nécessaire,https://toapis.cn) et importez une image source avecPOST /v1/uploads/images. - Testez une édition guidée par prompt sur
gpt-image-2avecreference_images,size: "1:1"etresolution: "1k". - Si vous avez besoin d'un masque au pixel près, passez sur
gpt-image-2-official, importez un masque RGBA correspondant à la première image et envoyezimage_urlsplusmask_url. - Conservez l'
idde tâche, interrogezGET /v1/images/generations/{id}avec un délai borné et respectezRetry-Aftersur429. - Ensuite : le guide 4K des formats d'image si vous augmentez
resolution, et le guide de l'API pour la carte complète des paramètres.







