Aller au contenu

Entrée multimodale

L’entrée multimodale permet aux modèles de traiter non seulement du texte, mais aussi des images, de l’audio et d’autres formes de contenu. RouteAPI prend en charge la transmission de contenu multimodal sur /v1/chat/completions (format OpenAI) et /v1/messages (format Claude), et gère automatiquement la conversion de format entre différents protocoles en amont.

Type de modalitéDescription
Image (Vision)Formats PNG, JPEG, WebP, GIF pour la compréhension d’images, l’OCR, l’analyse de graphiques
AudioCertains modèles prennent en charge l’entrée audio pour la compréhension vocale, la transcription, etc.
VidéoCertains modèles prennent en charge l’entrée de trames vidéo en divisant la vidéo en séquences d’images clés

Actuellement, la prise en charge de l’entrée d’image est la plus répandue, presque tous les modèles de vision grand public la prenant en charge. L’entrée audio et vidéo dépend des capacités spécifiques du modèle.

Les modèles suivants prennent en charge l’entrée d’image (liste non exhaustive) :

Famille de modèlesID de modèle typique
OpenAI GPT-4 Visiongpt-4o, gpt-4-turbo, gpt-5.5
Claude Visionclaude-sonnet-4-5, claude-opus-4-5
Gemini Visiongemini-2.0-flash, gemini-2.5-pro
Azure OpenAIazure-gpt-4o

Commencez par vérifier via le point de terminaison de liste des modèles que le modèle est disponible dans votre compte :

Fenêtre de terminal
curl https://api.routeapi.ai/v1/models \
-H "Authorization: Bearer $ROUTEAPI_KEY"

Ce point de terminaison ne retourne aucun champ indiquant la capacité d’entrée d’image. Pour savoir si l’entrée visuelle est prise en charge, référez-vous à la documentation du fournisseur ou à une requête réelle contenant une image.

FormatMIME TypeDescription
PNGimage/pngFormat sans perte, adapté aux captures d’écran et aux graphiques
JPEGimage/jpegCompression avec perte, adapté aux photos
WebPimage/webpFormat moderne avec petite taille et haute qualité
GIFimage/gifFormat non animé (seule la première image est utilisée)

Différents modèles ont différentes limites de taille d’image. Recommandations générales :

LimiteValeur recommandéeDescription
Taille d’image unique< 20 MBLes très grandes images augmentent le temps de traitement et le coût
Résolution d’imageCôté long ≤ 2048pxLes hautes résolutions sont automatiquement mises à l’échelle ou traitées par morceaux
Encodé en Base64< 32 MBLa taille totale de la requête est limitée par le service en amont

Il est recommandé de compresser les images avant le téléchargement, en réduisant la résolution tout en maintenant la lisibilité pour diminuer à la fois le temps de transmission et le coût en tokens.

Les images sont converties en tokens pour la facturation. Les images haute résolution consomment beaucoup plus de tokens que le texte :

  • Mode basse résolution (comme detail: "low" d’OpenAI) : Environ 85 tokens/image fixe.
  • Mode haute résolution (comme detail: "high") : Divisé par taille d’image ; une image 2048×2048 peut consommer 800-1500 tokens.

En production, choisissez le mode de résolution en fonction des besoins réels. Utilisez le mode low lorsqu’une reconnaissance fine n’est pas nécessaire.

Les images peuvent être transmises de deux manières : URL et encodage Base64.

Transmettez une URL d’image accessible publiquement pour que le service de modèle en amont la récupère :

Avantages :

  • Petite taille de requête, n’utilise pas votre bande passante de téléchargement.
  • Adapté aux images déjà hébergées sur CDN.

Inconvénients :

  • L’image doit être accessible publiquement ; les IP du service en amont doivent pouvoir y accéder.
  • Si le chargement de l’image échoue (problèmes réseau, authentification, lien expiré), la requête génèrera une erreur.

Cas d’usage : Images déjà sur des hébergeurs d’images publics ou CDN, pas besoin de téléchargement temporaire.

Lisez l’image sous forme de données binaires, encodez avec Base64 et intégrez directement dans la requête :

Avantages :

  • Pas besoin d’URL accessible publiquement, adapté aux images privées.
  • Requête autonome, ne dépend pas de la disponibilité du service externe.

Inconvénients :

  • L’encodage Base64 augmente la taille des données d’environ 33%.
  • Grande taille de requête, temps de téléchargement plus long.

Cas d’usage : Images privées téléchargées par l’utilisateur, fichiers locaux, captures d’écran temporaires sans URL publique.

ComparaisonMéthode URLMéthode Base64
Taille de requêtePetite (juste chaîne URL)Grande (Base64 ~1,33× fichier original)
Vitesse de téléchargementRapideLente
Accessibilité de l’imageDoit être accessible publiquementAucune exigence, images privées OK
Dépendances externesDépend du serveur d’images et de la récupération en amontAucune dépendance externe
Cas d’usageHébergeurs d’images publics, CDNTéléchargements utilisateur, fichiers locaux

Dans /v1/chat/completions, les images sont transmises via le tableau content, où chaque élément est un bloc de contenu distingué par type pour le texte et les images.

content peut être une chaîne (texte brut) ou un tableau (multimodal) :

{
"role": "user",
"content": [
{ "type": "text", "text": "Qu'y a-t-il dans cette image ?" },
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}

Champs du bloc de contenu image_url :

ChampTypeRequisDescription
typestringOuiFixé à "image_url"
image_url.urlstringOuiURL d’image ou URI de données Base64
image_url.detailstringNonMode de résolution : "low", "high", "auto" (par défaut)

detail contrôle la résolution et le coût du traitement d’image :

ValeurComportementConsommation de tokens
"low"Mode basse résolution, image réduite à taille fixe (ex : 512×512)Environ 85 tokens fixes
"high"Mode haute résolution, image traitée par morceaux, préserve les détailsSelon le nombre de morceaux, généralement des centaines à des milliers de tokens
"auto"Le modèle choisit automatiquement (par défaut)Dépend de la stratégie du modèle

Exemple de différence de coût :

  • Une simple capture d’écran avec "low" pourrait ne nécessiter que 85 tokens (~0,0001 $).
  • La même image avec "high" pourrait consommer 800 tokens (~0,001 $).

Pour les scénarios qui ne nécessitent pas de reconnaître du petit texte ou des détails (comme “quel est cet animal” ou “quelle est la couleur du thème de l’interface”), "low" est suffisant. Utilisez "high" uniquement lorsque vous avez besoin d’OCR, de lecture de valeurs de graphiques ou de reconnaissance de petits objets.

{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
"detail": "high"
}
},
{ "type": "text", "text": "Décrivez le contenu de cette image" }
]
}
]
}

Base64 nécessite le format URI de données : data:<mime_type>;base64,<encoded_data>.

{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
}
},
{ "type": "text", "text": "Quel texte y a-t-il dans cette image ?" }
]
}
]
}

Notez que la chaîne Base64 peut être très longue ; l’exemple ci-dessus est tronqué. En usage réel, l’encodage complet peut faire de plusieurs centaines de Ko à plusieurs Mo.

Dans /v1/messages, les images sont transmises via des blocs de type image dans le tableau content, avec une structure significativement différente du format OpenAI.

{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
}
},
{ "type": "text", "text": "Décrivez cette image" }
]
}

Le champ source spécifie la source de l’image de deux manières :

ChampTypeRequisDescription
typestringOuiFixé à "base64"
media_typestringOuiType MIME, comme image/jpeg, image/png
datastringOuiDonnées d’image encodées en Base64 (sans préfixe data:)

Notez que le Base64 du format Claude ne nécessite pas le préfixe URI de données ; transmettez directement la chaîne encodée.

{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
}
ChampTypeRequisDescription
typestringOuiFixé à "url"
urlstringOuiURL d’image accessible publiquement
{
"type": "image",
"source": {
"type": "url",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
}
{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
}
},
{ "type": "text", "text": "Quel est cet insecte ?" }
]
}
]
}

Le format natif de Gemini utilise un tableau parts au lieu de content, avec une structure assez différente. RouteAPI gère la conversion en interne, donc lors de l’appel de modèles Gemini en utilisant le format OpenAI ou Claude, vous n’avez pas besoin de vous soucier des détails du format natif. Ce qui suit est pour référence uniquement.

{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Décrivez cette image" },
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}
ChampDescription
inlineData.mimeTypeType MIME
inlineData.dataDonnées encodées en Base64

Gemini prend également en charge la référence de fichiers téléchargés vers les services Google via URI de fichier :

{
"fileData": {
"mimeType": "image/jpeg",
"fileUri": "gs://bucket-name/path/to/image.jpg"
}
}

En pratique, lors de l’appel de modèles Gemini via RouteAPI, utilisez le format OpenAI ou Claude ; RouteAPI convertira automatiquement.

Tous les modèles de vision grand public prennent en charge la transmission de plusieurs images dans une seule requête.

Placez plusieurs blocs d’images dans le tableau content / parts :

Format OpenAI :

{
"role": "user",
"content": [
{ "type": "text", "text": "Comparez les différences entre ces deux images" },
{
"type": "image_url",
"image_url": { "url": "https://example.com/image1.jpg" }
},
{
"type": "image_url",
"image_url": { "url": "https://example.com/image2.jpg" }
}
]
}

Format Claude :

{
"role": "user",
"content": [
{ "type": "text", "text": "Quelles sont les similitudes et différences entre ces deux images ?" },
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/before.jpg" }
},
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/after.jpg" }
}
]
}

Le modèle comprend les images dans l’ordre du tableau. Si le texte fait référence à “la première image” ou “la deuxième image”, le modèle correspondra par ordre d’apparition. Il est recommandé de placer le texte explicatif avant ou après toutes les images, et non intercalé, pour une sémantique plus claire :

{
"content": [
{ "type": "text", "text": "La première est une capture d'écran de l'interface utilisateur, la seconde est une maquette de design. Veuillez comparer les différences et fournir des suggestions de modification." },
{ "type": "image_url", "image_url": { "url": "..." } },
{ "type": "image_url", "image_url": { "url": "..." } }
]
}

Vous pouvez également alterner texte et images pour une explication étape par étape :

{
"content": [
{ "type": "text", "text": "Voici l'interface d'origine :" },
{ "type": "image_url", "image_url": { "url": "https://example.com/old.jpg" } },
{ "type": "text", "text": "Voici l'interface améliorée :" },
{ "type": "image_url", "image_url": { "url": "https://example.com/new.jpg" } },
{ "type": "text", "text": "Veuillez résumer les améliorations." }
]
}

L’efficacité réelle dépend de la capacité du modèle à comprendre l’ordre des blocs de contenu ; les modèles de vision grand public peuvent généralement gérer cela correctement.

Certains modèles prennent en charge l’entrée audio pour la compréhension vocale, la transcription, l’analyse de sentiments, etc. Le support actuel est moins répandu que pour les images.

Dépend des modèles spécifiques, les formats courants incluent :

  • WAV (audio/wav)
  • MP3 (audio/mpeg)
  • OGG (audio/ogg)
  • FLAC (audio/flac)

Comme pour les images, l’audio prend en charge à la fois les méthodes URL et Base64. Exemple de format OpenAI (en supposant la prise en charge du modèle) :

{
"role": "user",
"content": [
{
"type": "input_audio",
"input_audio": {
"data": "<base64-encoded-audio>",
"format": "wav"
}
},
{ "type": "text", "text": "Transcrivez cet audio et résumez les points clés" }
]
}

Les noms de champs et la structure réels dépendent du protocole du modèle. Avant utilisation, consultez la documentation du modèle sélectionné ou vérifiez le champ supports_audio_input via le point de terminaison de liste des modèles.

Les exemples suivants montrent l’implémentation de bout en bout de la compréhension d’image en curl, Python et Node.js.

Donnez une image et faites décrire son contenu par le modèle.

curl (format OpenAI, méthode URL) :

Fenêtre de terminal
curl https://api.routeapi.ai/v1/chat/completions \
-H "Authorization: Bearer $ROUTEAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
},
{ "type": "text", "text": "Décrivez en détail le contenu et l'\''atmosphère de cette image" }
]
}
]
}'

Python (SDK OpenAI, méthode Base64) :

import base64
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ROUTEAPI_KEY"],
base_url="https://api.routeapi.ai/v1",
)
# Lire l'image locale et encoder en Base64
with open("image.jpg", "rb") as f:
image_data = base64.b64encode(f.read()).decode("utf-8")
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{image_data}"
},
},
{"type": "text", "text": "Qu'y a-t-il dans cette image ?"},
],
}
],
)
print(response.choices[0].message.content)

Node.js (paquet openai, méthode URL) :

import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.ROUTEAPI_KEY,
baseURL: 'https://api.routeapi.ai/v1',
});
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: [
{
role: 'user',
content: [
{
type: 'image_url',
image_url: {
url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/320px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg',
},
},
{ type: 'text', text: 'Résumez le thème de cette image en une phrase' },
],
},
],
});
console.log(response.choices[0].message.content);

Analyse de graphiques et de visualisation de données

Section intitulée « Analyse de graphiques et de visualisation de données »

Téléchargez une capture d’écran de graphique et faites lire et analyser les données par le modèle :

Python (format Claude, Base64) :

import base64
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ROUTEAPI_KEY"],
base_url="https://api.routeapi.ai",
)
with open("chart.png", "rb") as f:
image_data = base64.b64encode(f.read()).decode("utf-8")
message = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{
"type": "text",
"text": "Quelle tendance ce graphique montre-t-il ? Veuillez extraire les points de données clés et fournir une analyse.",
},
],
}
],
)
print(message.content[0].text)

Extrayez le contenu textuel de captures d’écran ou de photos :

curl (format OpenAI, haute résolution) :

Fenêtre de terminal
curl https://api.routeapi.ai/v1/chat/completions \
-H "Authorization: Bearer $ROUTEAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Extrayez tout le texte de l'\''image, en maintenant le format et la structure d'\''origine"
}
]
}
]
}'

Pour les scénarios OCR, utilisez "detail": "high" pour garantir la précision de reconnaissance, surtout pour les petits caractères ou le texte dense.

Comparez les différences entre deux images ou plus :

Python (format OpenAI, plusieurs images) :

from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ROUTEAPI_KEY"],
base_url="https://api.routeapi.ai/v1",
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Comparez les deux images suivantes et trouvez 5 différences majeures entre elles :",
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/before.jpg"},
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/after.jpg"},
},
],
}
],
)
print(response.choices[0].message.content)

Mélangez images et texte dans des conversations multi-tours :

from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ROUTEAPI_KEY"],
base_url="https://api.routeapi.ai/v1",
)
messages = [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {"url": "https://example.com/product.jpg"},
},
{"type": "text", "text": "Quelles sont les principales caractéristiques de ce produit ?"},
],
}
]
response = client.chat.completions.create(model="gpt-4o", messages=messages)
messages.append(response.choices[0].message)
print("Premier tour :", response.choices[0].message.content)
# Continuer à poser des questions (texte simple)
messages.append({"role": "user", "content": "À quel type d'utilisateurs convient-il ?"})
response = client.chat.completions.create(model="gpt-4o", messages=messages)
print("Deuxième tour :", response.choices[0].message.content)

Les images ne doivent être transmises qu’une fois au premier tour ; dans les tours suivants, le modèle se souviendra du contenu de l’image (dans la fenêtre de contexte) sans nécessiter de re-téléchargement.

Effectuez l’optimisation nécessaire avant de télécharger des images pour réduire les coûts et améliorer la vitesse de réponse :

OptimisationRecommandation
TailleGardez le côté long dans les 2048px sauf si vous avez vraiment besoin de reconnaître plus de détails
FormatUtilisez PNG pour les captures d’écran et graphiques, JPEG pour les photos, WebP pour une compression ultime
CompressionQualité JPEG 80-90% est suffisante, différence visuelle minimale mais taille significativement réduite
RecadrageSupprimez les zones non pertinentes (grands espaces vides, filigranes, bordures), ne gardez que le contenu clé

N’écrasez pas les images au point de les rendre méconnaissables pour économiser des tokens ; si le modèle ne peut pas les reconnaître, c’est en fait un gaspillage.

Le coût de l’entrée multimodale provient principalement des images :

ScénarioConsommation typique de tokensEstimation de coût (GPT-4o)
Image basse résolution (detail: "low")~85 tokens0,0001 $
Petite image haute résolution (500×500, detail: "high")~200 tokens0,0003 $
Grande image haute résolution (2000×2000, detail: "high")~800 tokens0,0012 $
Plusieurs images haute résolution (5 images, detail: "high")~4000 tokens0,006 $

Les tarifs spécifiques dépendent du modèle sélectionné ; ce qui précède n’est qu’un exemple. Recommandations de production :

  1. Par défaut, utilisez detail: "auto" ou "low", laissez le modèle ou les besoins de l’utilisateur déterminer la résolution.
  2. Utilisez "high" uniquement lorsqu’une reconnaissance fine est clairement nécessaire (OCR, données de graphiques, détection de petits objets).
  3. Enregistrez l’utilisation de tokens pour chaque requête (champ usage de la réponse) pour identifier les anomalies de coût.

L’entrée multimodale introduit des points de défaillance supplémentaires nécessitant un traitement ciblé :

{
"error": {
"message": "Unsupported image format",
"type": "invalid_request_error"
}
}

Solution : Confirmez que le type MIME est correct, ou convertissez en PNG/JPEG.

{
"error": {
"message": "Image size exceeds limit",
"type": "invalid_request_error"
}
}

Solution : Compressez l’image ou réduisez la résolution et réessayez.

{
"error": {
"message": "Failed to fetch image from URL",
"type": "invalid_request_error"
}
}

Solution :

  • Confirmez que l’URL est accessible publiquement sans authentification.
  • Testez si les IP du service en amont peuvent accéder à cette URL (pare-feu, restrictions géographiques).
  • Passez à la méthode Base64 pour éviter la dépendance au service externe.
{
"error": {
"message": "Invalid base64 encoding",
"type": "invalid_request_error"
}
}

Solution : Vérifiez si l’encodage Base64 est complet et si le format est correct (le format OpenAI nécessite le préfixe data:, le format Claude non).

RisqueMesures de protection
Fuite d’image URLAssurez-vous que l’URL pointe vers une image sans informations sensibles, ou utilisez des liens temporaires authentifiés
Attaques de taille Base64Limitez la taille maximale de téléchargement d’image de l’utilisateur (ex : 20 MB) pour éviter les requêtes surdimensionnées
Attaques par injectionNe concaténez pas directement les URL d’images téléchargées par l’utilisateur dans les commandes système ou SQL
Hallucinations du modèleLes résultats de compréhension d’image peuvent être inexacts ; les scénarios à haut risque (médical, juridique, financier) nécessitent une révision humaine
  • Les capacités de vision, les formats d’image pris en charge et le nombre maximal d’images dépendent du modèle sélectionné ; testez et vérifiez avant la production.
  • Le paramètre detail n’a de sens que dans le format OpenAI ; le format Claude n’a pas de paramètre correspondant.
  • Différents modèles ont différentes stratégies de traitement de résolution ; la même image peut consommer des tokens significativement différents selon les modèles.
  • Dans les réponses en streaming, les résultats de traitement du contenu d’image sont généralement retournés d’un coup tôt ou tard dans le flux, et non en streaming caractère par caractère.
  • Enregistrez l’ID de requête, l’ID de modèle, le code d’état et l’utilisation de tokens pour chaque requête afin de faciliter le dépannage des problèmes de coût et de qualité. Voir Erreurs et débogage pour plus de détails.