input_image vs image_url : les deux syntaxes

Deux API, deux syntaxes

L’API xAI propose deux endpoints pour interagir avec Grok, et chacun utilise une syntaxe différente pour envoyer des images. Comprendre ces différences est essentiel pour écrire du code correct et éviter des erreurs frustrantes.

API Responses : input_image (recommandée)

L’API Responses est le nouvel endpoint 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": "Décris cette image."
    }
  ]
}

Caractéristiques

• Le type est input_image (pas image_url)
• L’URL ou le Data URI est directement dans image_url (pas d’objet imbriqué)
• Le detail est au même niveau que image_url
• Le texte utilise le type input_text
• Le tableau input remplace le tableau messages de Chat Completions

Python SDK

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": "Décris cette image."
        }
    ],
    store=False
)

print(response.output_text)

API Chat Completions : image_url (legacy)

L’API Chat Completions est l’endpoint legacy, maintenu pour la compatibilité avec les SDKs OpenAI existants. Si vous migrez 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": "Décris cette image."
        }
      ]
    }
  ]
}

Caractéristiques

• Le type est image_url (pas input_image)
• L’URL est dans un objet imbriqué image_url.url (double imbrication)
• Le detail est à l’intérieur de l’objet image_url
• Le texte utilise le type text (pas input_text)
• Les messages ont un role (system, user, assistant)

Python avec SDK OpenAI

from openai import OpenAI

client = OpenAI(
    api_key="votre-clé-xai",
    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": "Décris cette image."
            }
        ]
    }]
)

print(response.choices[0].message.content)

Tableau comparatif

Erreurs courantes de syntaxe

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 double imbrication en 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": "Décris."}  # Non !
]

# CORRECT
input=[
    {"type": "input_text", "text": "Décris."}  # Oui !
]

Quand utiliser quelle API

• Nouveau projet : utilisez l’API Responses. Elle donne accès aux dernières fonctionnalités et au stockage des conversations
• Migration depuis OpenAI : commencez avec Chat Completions pour minimiser les changements de code, puis migrez vers l’API Responses progressivement
• Images sensibles : l’API Responses avec store: false ou l’API Chat Completions (stateless par nature)

Points clés à retenir

• L’API Responses utilise input_image + input_text, l’API Chat Completions utilise image_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élangez jamais les syntaxes des deux API dans une même requête
• Vérifiez toujours le type d’objet (input_image vs image_url) pour éviter les erreurs silencieuses

Testez vos connaissances

La vision par l’API xAI : formats, tokens, syntaxes — tout est en place ?

1. Comment envoie-t-on une image à l'API ?

Réponse : Par URL ou en Base64, dans un message au contenu mixte — en respectant les contraintes de formats et de taille documentées.

2. Que règle le paramètre de détail (auto, low, high) ?

Réponse : La finesse d’analyse et son coût : low économise les tokens pour les usages grossiers, high maximise la précision (OCR, détails fins), auto laisse l’API arbitrer.

3. Comment se calcule le coût d'une image ?

Réponse : En tokens image — de 256 à 1792 selon la résolution et le détail : dimensionner ses images et son niveau de détail est le premier levier d’optimisation.

4. Que permet la comparaison multi-images ?

Réponse : Envoyer plusieurs images dans une même requête et raisonner dessus — différences, évolutions, cohérence — le nombre d’images par requête n’étant pas limité.

5. input_image ou image_url : que choisir ?

Réponse : input_image est la syntaxe moderne de la Responses API ; image_url subsiste en héritage Chat Completions — pour le nouveau code, la syntaxe moderne s’impose.

Bon format, bon détail, bonne syntaxe : la vision se pilote comme le texte — au token près.