Générer des images 4K natives avec GPT Image 2 : formats d'image et workflows d'upscaling
Modèle cible :
gpt-image-2
Endpoint d'inférence :https://api.toapis.com/v1/images/generations
Associé : Guide de l'API GPT Image 2 · Inpainting et outpainting · Miroir et proxy global · Référence des tailles de l'API
1. TL;DR et vue d'ensemble des performances
- Objectif : produire une image prête pour l'impression ou pour un visuel hero au palier 4K documenté, avec le format d'image dont vous avez réellement besoin, à partir d'une seule requête
gpt-image-2. - Contrat :
POST /v1/images/generationsavec l'ID de modèlegpt-image-2.sizeest un format d'image (1:1,16:9et les autres ratios documentés).resolutionvaut1k,2kou4k. La référence officielle publie les dimensions en pixels résultantes pour chaque paire. - Ce qu'il ne faut pas envoyer :
size: "2048x2048", un flagquality: "hd"sur legpt-image-2exact, ou un champ inventéupscale: truequi prétend transformer un rendu 2048 px en3840x2160. Le 4K est une valeurresolutionà part entière. - Protocole asynchrone : l'appel de soumission renvoie un
idde tâche. InterrogezGET /v1/images/generations/{id}(ouGET /v1/tasks/{id}) jusqu'au statutcompletedoufailed. Les tâches 4K peuvent prendre plus de temps que les brouillons 1K ; un timeout client ne prouve pas que la tâche a échoué. - FinOps : faites vos brouillons en
1k, promouvez les prompts acceptés en4ket confirmez le tarif actuel par palier. Ne recopiez pas d'anciennes lignes de prix 1024 px / 2048 px dans une prévision.
2. Formats d'image, paliers de résolution et sortie 4K native
Le contrat actuel de gpt-image-2 sépare la forme du palier. size choisit le format d'image ; resolution choisit le palier de qualité ; le service dérive la largeur et la hauteur en pixels des deux. C'est pourquoi une « image 4K » n'est pas toujours 3840x2160 — cette taille est le résultat documenté de size: "16:9" plus resolution: "4k". Une sortie carrée en 4K est documentée comme 2880x2880.
Les ratios prédéfinis listés dans la référence officielle sont :
1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21
Vous pouvez envoyer auto et laisser le fournisseur amont choisir, mais le ratio final et la taille en pixels ne sont alors pas garantis. Le gpt-image-2 exact ne documente pas de champ custom de taille en pixels ; les ratios width:height personnalisés (par exemple 7:4) sont documentés sur gpt-image-2-vip et gpt-image-2-official, sous réserve de leurs propres limites (côtés multiples de 16, grand côté au maximum 3 840 px, ratio au maximum 3:1, total de pixels entre 655 360 et 8 294 400).
Le tableau des tailles de la référence de l'API pour le gpt-image-2 exact est :
| size | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
3:2 | 1536x1024 | 2048x1360 | 3520x2336 |
2:3 | 1024x1536 | 1360x2048 | 2336x3520 |
4:3 | 1024x768 | 2048x1536 | 3312x2480 |
3:4 | 768x1024 | 1536x2048 | 2480x3312 |
5:4 | 1280x1024 | 2560x2048 | 3216x2576 |
4:5 | 1024x1280 | 2048x2560 | 2576x3216 |
16:9 | 1536x864 | 2048x1152 | 3840x2160 |
9:16 | 864x1536 | 1152x2048 | 2160x3840 |
2:1 | 2048x1024 | 2688x1344 | 3840x1920 |
1:2 | 1024x2048 | 1344x2688 | 1920x3840 |
21:9 | 2016x864 | 2688x1152 | 3840x1648 |
9:21 | 864x2016 | 1152x2688 | 1648x3840 |
Deux mises en garde accompagnent ce tableau :
- Le playground ToAPIs actuel conserve
3:2et2:3en 4K, mais omet5:4et4:5lorsque la résolution est 4K. Le tableau des tailles ci-dessus liste pourtant des pixels 4k pour ces deux ratios. Si votre produit a besoin de5:4ou4:5en 4k, confirmez par une requête réelle plutôt que de supposer que le filtre du playground correspond à la limite de l'API. - Les minuscules (
4k) et les majuscules (4K) apparaissent sur différentes surfaces. Les exemples officiels degpt-image-2utilisent les minuscules ; la configuration du playground utilise1K/2K/4K. Suivez la référence de l'API dans vos clients et ne traitez pas la casse comme un second paramètre.

Figure 1 : la résolution est un champ de requête à part entière. Le chemin documenté consiste à demander directement du 4k, pas à inventer un flag d'upscaler en post-traitement.
Il n'existe aucun commutateur upscale: true documenté chez ToAPIs qui prenne un rendu natif 2048 px pour renvoyer 3840x2160. Si vous avez déjà une image 1K ou 2K et que vous en voulez une plus grande, la manœuvre prise en charge est une nouvelle génération (éventuellement avec le brouillon dans reference_images) à resolution: "4k". Ne promettez pas de fidélité typographique, de « masters d'impression 300 DPI » ni d'upscaling sans artefacts tant que vous n'avez pas mesuré ces propriétés sur vos propres assets.
Le gpt-image-2 exact accepte également background: "transparent" en option et jusqu'à 14 URL reference_images. Il n'expose pas quality dans le contrat actuel du playground ; quality est un champ propre à des ID comme gpt-image-2-vip.
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.
Étape 1 : envoi cURL en 4K natif
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": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
"size": "16:9",
"resolution": "4k",
"n": 1,
"response_format": "url"
}'
Cette requête cible documentairement 3840x2160. Pour un master carré en 4K, passez size à 1:1 (documenté comme 2880x2880). Pour un frame story en 9:16, utilisez size: "9:16" (documenté comme 2160x3840).
Étape 2 : helper Python de brouillon puis promotion
Itérez en 1k, conservez le prompt accepté (et les URL de référence optionnelles), puis renvoyez en 4k. Le helper d'interrogation reprend le même contrat asynchrone que celui du guide miroir et proxy.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_image(
prompt: str,
size: str = "16:9",
resolution: str = "1k",
model: str = "gpt-image-2",
reference_images: list[str] | None = None,
) -> str:
payload = {
"model": model,
"prompt": prompt,
"size": size,
"resolution": resolution,
"n": 1,
"response_format": "url",
}
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(ENDPOINT, headers=HEADERS, 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 = 300) -> 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__":
prompt = (
"Wide architectural photograph of a concrete pavilion at dusk, "
"still water in the foreground, no typography, no logos"
)
draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
print("Draft:", draft_id, poll_image_task(draft_id))
final_id = dispatch_image(prompt, size="16:9", resolution="4k")
print("4K:", final_id, poll_image_task(final_id, deadline_s=300))
Accordez aux interrogations 4K un délai plus long qu'aux brouillons 1K. Conservez l'id de tâche immédiatement, afin qu'un timeout client puisse être résolu plus tard par une vérification de statut. Si vous faites ensuite passer le client sur gpt-image-2-vip (ratios personnalisés, quality) ou gpt-image-2-official, changez une variable à la fois et relisez la référence de cet ID — les unités de facturation ne sont pas automatiquement identiques.
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 | Vérifiez que size est un ratio documenté, que resolution vaut 1k / 2k / 4k et que vous n'avez pas envoyé de chaîne de pixels comme 2048x2048 ni un flag upscale non documenté |
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 ; les tâches 4K peuvent encore être in_progress après un timeout client |
5. Tarifs et ROI FinOps
- Ne réutilisez pas d'anciens prix unitaires comme
$0.024pour 1024 px ou$0.072pour 2048 px. Ces lignes appartiennent à un contrat de taille obsolète. - 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. Ne l'utilisez que comme comparaison publiée. Confirmez le tarif applicable à votre compte et à l'ID de modèle exact que vous appelez. - Une boucle économique consiste à faire des brouillons en
1k, puis à promouvoir le prompt accepté (et les références) en4k. Deux tâches réussies correspondent à deux images facturables, sauf si les conditions de votre compte indiquent le contraire. Il n'existe aucun raccourci gratuit documenté du type « upscaler le même prompt ». - Les prix par token du fournisseur officiel et les prix par requête de ToAPIs ne sont pas interchangeables. Si vous passez à
gpt-image-2-vipou à une SKU de canal officiel, relisez la grille tarifaire de cet ID. - 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 4K est une valeur resolution à part entière, pas un flag upscale ; les dimensions en pixels dépendent de size et de resolution ; n'envoyez pas 1024x1024 comme size ; confirmez 5:4 / 4:5 en 4k auprès de l'API en direct si vous avez besoin de ces ratios ; confirmez les tarifs publiés 1K / 2K / 4K sur votre compte.
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 testez l'extrait cURL avecsize: "16:9"etresolution: "1k". - Promouvez le même prompt en
resolution: "4k"et confirmez la taille en pixels documentée pour ce ratio (pour16:9,3840x2160). - Conservez l'
idde tâche, accordez un délai plus long aux interrogations 4K et respectezRetry-Aftersur429. - Ensuite : le guide inpainting et outpainting si vous éditez un frame existant, et le guide de l'API pour la carte complète des paramètres.







