Format d'image OpenAI

Informations communes

• URL de base : https://api.routeapi.ai
• Authentification : Authorization: Bearer $ROUTEAPI_KEY avec une clé API commençant par sk- (à créer sur la page Clés API). Les clés de gestion commençant par rat_ ne peuvent pas appeler de modèle.
• Format d’erreur : {"error": {"message": "...", "type": "...", "code": "..."}} ; voir Erreurs courantes pour la signification des codes de statut.

RouteAPI expose la génération d’images via les points de terminaison images compatibles OpenAI. Cette page couvre l’enveloppe de requête commune et la famille OpenAI gpt-image — gpt-image-2 est le modèle en vente. Les autres fournisseurs sont adaptés vers les mêmes points de terminaison ; leur comportement propre est documenté séparément : Nano Banana pour les modèles d’image Gemini, Seedream pour ByteDance.

La capacité d’un modèle à générer des images est visible dans la liste des modèles : son supported_endpoint_types contient image-generation. Voir Modèles pour savoir lire ce champ.

Points de terminaison

POST /v1/images/generations
POST /v1/images/edits

URL complètes :

https://api.routeapi.ai/v1/images/generations
https://api.routeapi.ai/v1/images/edits

/v1/images/generations prend un corps JSON. /v1/images/edits prend du multipart/form-data — ou, sur les canaux compatibles OpenAI, un corps JSON qui référence les images par URL ou Base64 (voir Modifications via JSON).

Générer une image

Paramètres de requête

Champ	Type	Requis	Description
model	string	Oui	ID de modèle issu de GET /v1/models, par exemple gpt-image-2
prompt	string	Oui	Description textuelle de l’image à générer
n	integer	Non	Nombre d’images, jusqu’à 128. Omis ou 0 est traité comme 1
size	string	Non	Taille de sortie telle que 1024x1024, 1024x1536, ou un palier comme 1K / 2K selon le modèle. Dans un corps JSON, utilisez x comme séparateur — un × pleine largeur est rejeté avec 400
quality	string	Non	Niveau de qualité tel que standard, hd, high, medium, low ou auto. Les valeurs acceptées dépendent du modèle
response_format	string	Non	url ou b64_json. Transmis à l’amont ; la valeur honorée par un modèle est décidée par le fournisseur
style	string	Non	Indication de style (par exemple vivid ou natural). Pertinent uniquement pour les modèles qui l’acceptent
user	string	Non	Identifiant d’utilisateur final transmis à l’amont
watermark	boolean	Non	Faut-il appliquer un filigrane à la sortie, pour les fournisseurs qui le prennent en charge

Les champs supplémentaires compris par la passerelle incluent background, output_format, output_compression, input_fidelity, moderation et partial_images ; ils sont transmis aux amonts compatibles OpenAI lorsqu’ils sont présents. Les champs JSON inconnus sont abandonnés et non transmis, sauf si le canal est en mode passthrough du corps de requête.

Note

Les valeurs par défaut sont propres à chaque modèle. La passerelle injecte quality: "auto" pour gpt-image-1 en génération JSON et n’injecte aucune valeur par défaut pour gpt-image-2. L’ancien dall-e-3 utilise par défaut size: "1024x1024" et quality: "standard" et n’accepte que 1024x1024, 1024x1792 et 1792x1024.

prompt est requis par le modèle amont mais n’est pas rejeté d’emblée par RouteAPI : un prompt vide est transmis, et c’est le fournisseur qui décide de le refuser.

Un n supérieur à 128 est rejeté avant le transfert de la requête.

Exemple de requête

curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A calico cat playing a piano on a small stage, soft studio lighting",
    "size": "1024x1024",
    "n": 1
  }'

Python (SDK OpenAI)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A calico cat playing a piano on a small stage, soft studio lighting",
    size="1024x1024",
    n=1,
)

for item in result.data:
    print(item.url or item.b64_json[:40])

Réponse

Les canaux compatibles OpenAI renvoient le corps amont tel quel. Selon le modèle, data[] contient b64_json, url, ou les deux — lisez celui qui est présent.

{
  "created": 1740000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4160,
    "total_tokens": 4172
  }
}

Champ	Description
created	Horodatage Unix de la génération
data	Tableau des images générées, une entrée par image
data[].url	URL de l’image, lorsque l’amont renvoie des URL
data[].b64_json	Octets de l’image en Base64, lorsque l’amont renvoie du Base64
data[].revised_prompt	Prompt réécrit, si le modèle en renvoie un
usage	Utilisation de tokens, présent seulement si l’amont la renvoie

Utilisez celui de url / b64_json qui est présent ; ne supposez pas que les deux existent, et traitez usage comme facultatif lors de l’analyse.

Modifier une image

POST /v1/images/edits modifie une image existante à l’aide de prompt et, éventuellement, d’un masque.

Champs multipart

Champ	Type	Requis	Description
model	string	Oui	ID de modèle issu de GET /v1/models
image	file	Oui	L’image source. Répétez le champ, ou utilisez image[], pour en envoyer plusieurs
prompt	string	Oui	Instruction décrivant la modification
mask	file	Non	Image de masque marquant la zone à modifier. La sémantique du masque est définie par le modèle amont
n	integer	Non	Nombre de résultats, jusqu’à 128 (par défaut 1)
size	string	Non	Taille de sortie, selon les mêmes règles que la génération
quality	string	Non	Niveau de qualité accepté par le modèle
watermark	boolean	Non	Faut-il appliquer un filigrane à la sortie

Les autres champs de formulaire sont transmis tels quels aux amonts compatibles OpenAI, donc des paramètres comme response_format ou input_fidelity passent aussi.

Exemple de requête multipart

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F model="gpt-image-2" \
  -F prompt="Replace the background with a sunset beach" \
  -F image=@"cat.png" \
  -F size="1024x1024"

Python (SDK OpenAI)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

with open("cat.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="Replace the background with a sunset beach",
        size="1024x1024",
    )

print(result.data[0].b64_json[:40])

Modifications via JSON

Sur les canaux compatibles OpenAI, /v1/images/edits accepte aussi un corps JSON. RouteAPI télécharge ou décode chaque référence d’image et reconstruit une requête multipart en amont — utilisez ceci lorsque vos images sont déjà hébergées à une URL ou sont des chaînes Base64.

curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Repaint this photo as a watercolor illustration",
    "images": [
      { "image_url": "https://example.com/photo.png" }
    ],
    "size": "1024x1024"
  }'

Chaque entrée de images peut contenir image_url (ou url), sous forme de lien http(s) ou de chaîne data:image/...;base64,.... mask utilise la même structure. Le tableau images est requis sur ce chemin ; un champ image seul n’est pas lu. D’autres familles de canaux peuvent encore attendre un vrai corps multipart, donc testez le modèle cible avant de vous appuyer sur les modifications JSON.

Autres fournisseurs sur les mêmes points de terminaison

Les points de terminaison et l’enveloppe prompt / n / size sont partagés, mais chaque adaptateur fournisseur les mappe différemment.

Famille de fournisseur	Page
Modèles d’image Google Gemini (gemini-*-image*)	Nano Banana
ByteDance Seedream (seedream-5.0-pro, seedream-5.0-lite)	Seedream

Facturation

Les modèles gpt-image sont facturés au token : les images générées comptent comme tokens de sortie au prix de sortie, et le prompt ainsi que les images de référence comptent comme tokens d’entrée. Des sorties plus grandes et de meilleure qualité consomment plus de tokens. Voir Tarification des modèles pour les règles complètes, et la page de détail du modèle pour confirmer la méthode applicable.

Sur les modèles facturés à l’image avec paliers de taille, le prix est choisi à partir du nombre de pixels du size demandé avant la sélection du canal ; n est facturé par image, et un size omis ou non reconnu retombe sur le prix unitaire le plus élevé.

Erreurs et limites

Statut	Signification	Cause typique
400	Requête invalide	model manquant, n supérieur à 128, size non pris en charge pour le modèle, × utilisé comme séparateur de taille dans un corps JSON
401	Échec d’authentification	Clé API manquante, invalide, expirée ou épuisée
403	Solde ou quota épuisé	insufficient_user_quota ou pre_consume_token_quota_failed ; rechargez ou augmentez le quota de la clé
429	Limitation de débit	Réduisez la concurrence
500	Erreur de conversion ou interne	La requête n’a pas pu être convertie pour le canal choisi, ou une modification n’avait aucune image utilisable
501	api_not_implemented	Le point de terminaison existe mais n’est pas pris en charge

POST /v1/images/variations n’est pas pris en charge et renvoie 501 avec le code api_not_implemented ; utilisez plutôt une modification par prompt. /v1/images/edits nécessite au moins une image — les noms de champs de formulaire image, image[] et de la forme image[0] sont tous reconnus.

Étapes suivantes

• Nano Banana — modèles d’image Gemini, y compris le chemin natif generateContent.
• Seedream — tailles, génération séquentielle et modifications ByteDance Seedream.
• Modèles — trouver les modèles d’image et confirmer la prise en charge de image-generation.
• Tarification des modèles — facturation au token ou à l’image, et paliers de taille.
• Erreurs courantes — codes de statut partagés et format du corps d’erreur.