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",
  "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",
    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",
  "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",
    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