input_image vs image_url: les deux syntaxes
Šajā lapā
Deux API, deux syntaxes
xAI propose deux points de terminaison pour interagir avec Grok, et chacun utilise une syntaxe différente pour envoyer des images. Comprendre ces différences est essentiel pour écrire un code correct et éviter des erreurs frustrantes.
API Responses : input_image (recommandé)
L’API Responses est le nouveau point de terminaison principal de xAI. Les nouvelles fonctionnalités y sont ajoutées en priorité. C’est l’API à privilégier pour tout nouveau projet.
Syntaxe
{
"model": "grok-4.5",
"store": false,
"input": [
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Describe this image."
}
]
}
Caractéristiques
- Le type est
input_image(et nonimage_url) - L’URL ou le Data URI va directement dans
image_url(pas d’objet imbriqué) detailse trouve au même niveau queimage_url- Le texte utilise le type
input_text - Le tableau
inputremplace le tableaumessagesdes Chat Completions
SDK Python
response = client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_image",
"image_url": "https://exemple.com/photo.jpg",
"detail": "high"
},
{
"type": "input_text",
"text": "Describe this image."
}
],
store=False
)
print(response.output_text)
API Chat Completions : image_url (héritage)
L’API Chat Completions est le point de terminaison hérité, maintenu pour assurer la compatibilité avec les SDK OpenAI existants. Si tu migres du code écrit pour OpenAI, cette API facilite la transition.
Syntaxe
{
"model": "grok-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Describe this image."
}
]
}
]
}
Caractéristiques
- Le type est
image_url(et noninput_image) - L’URL se trouve dans un objet imbriqué
image_url.url(double imbrication) detailréside à l’intérieur de l’objetimage_url- Le texte utilise le type
text(et noninput_text) - Les messages ont un
role(system, user, assistant)
Python avec le SDK OpenAI
from openai import OpenAI
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
response = client.chat.completions.create(
model="grok-4.5",
messages=[{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://exemple.com/photo.jpg",
"detail": "high"
}
},
{
"type": "text",
"text": "Describe this image."
}
]
}]
)
print(response.choices[0].message.content)
Tableau comparatif
| Aspect | API Responses | Chat Completions |
|---|---|---|
| Statut | Principal (recommandé) | Hérité (compatibilité) |
| Type d'image | input_image | image_url |
| Type de texte | input_text | text |
| URL de l'image | image_url: "..." | image_url.url: "..." |
| Gestion d'état | Avec état (previous_response_id) | Sans état (tout renvoyer) |
| Stockage | store: true/false | Non (sans état) |
| Outils serveur | web_search, x_search, code_interpreter | Limités |
Erreurs de syntaxe courantes
Erreur 1 : Mélanger les formats
# FAUX — Syntaxe Chat Completions dans l'API Responses
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Non !
]
# CORRECT — Syntaxe API Responses
input=[
{"type": "input_image", "image_url": "..."} # Oui !
]
Erreur 2 : Oublier la structure imbriquée dans Chat Completions
# FAUX — URL directe dans Chat Completions
{"type": "image_url", "image_url": "https://..."} # Non !
# CORRECT — Objet imbriqué
{"type": "image_url", "image_url": {"url": "https://..."}} # Oui !
Erreur 3 : Utiliser “text” au lieu de “input_text”
# FAUX — Type "text" dans l'API Responses
input=[
{"type": "text", "text": "Describe."} # Non !
]
# CORRECT
input=[
{"type": "input_text", "text": "Describe."} # Oui !
]
Quelle API utiliser quand ?
- Nouveau projet : utilise l’API Responses. Elle donne accès aux dernières fonctionnalités et au stockage des conversations.
- Migration depuis OpenAI : commence par Chat Completions pour minimiser les changements de code, puis migre progressivement vers l’API Responses.
- Images sensibles : API Responses avec
store: falseou API Chat Completions (native sans état).
Galvenās atziņas
- L’API Responses utilise
input_image+input_text, l’API Chat Completions utiliseimage_url+text - La structure de l’URL diffère : directe dans Responses, imbriquée dans Chat Completions
- L’API Responses est le choix recommandé pour tout nouveau développement
- Ne mélange jamais les syntaxes des deux API dans la même requête
- Vérifie toujours le type d’objet (
input_imagevsimage_url) pour éviter des erreurs silencieuses
Teste tes connaissances
Vision de l’API xAI : formats, jetons, syntaxes, tout est-il en place ?
1. Comment envoyer une image à l'API ?
Réponse : Via une URL ou en Base64, dans un message à contenu mixte, en respectant le format et les contraintes de taille documentés.
2. Que contrôle le paramètre detail (auto, low, high) ?
Réponse : La granularité de l’analyse et le coût : low économise des jetons pour des cas d’usage grossiers, high maximise la précision (OCR, détails fins), auto laisse l’API décider.
3. Comment le coût d'une image est-il calculé ?
Réponse : En jetons d’image, de 256 à 1792 selon la résolution et le niveau de détail : dimensionner tes images et choisir ton niveau de détail est le premier levier d’optimisation.
4. Que permet la comparaison multi-images ?
Réponse : D’envoyer plusieurs images dans une seule requête et de raisonner dessus — différences, évolutions, cohérence — sans limite sur le nombre d’images par requête.
5. input_image ou image_url : lequel choisir ?
Réponse : input_image est la syntaxe moderne de l’API Responses ; image_url persiste comme héritage des Chat Completions. Pour tout nouveau code, la syntaxe moderne est obligatoire.
Bon format, bon détail, bonne syntaxe : la vision se pilote comme le texte, jusqu’au jeton près.