Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

input_image vs image_url: les deux syntaxes

Nodarbība 12 no 12 Atjaunota 2026. gada 30. jūlijs Iesācējs
Šajā lapā
  1. Deux API, deux syntaxes
  2. API Responses : input_image (recommandé)
  3. API Chat Completions : image_url (héritage)
  4. Tableau comparatif
  5. Erreurs de syntaxe courantes
  6. Quelle API utiliser quand ?
  7. Galvenās atziņas
  8. Teste tes connaissances

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 non image_url)
  • L’URL ou le Data URI va directement dans image_url (pas d’objet imbriqué)
  • detail se trouve au même niveau que image_url
  • Le texte utilise le type input_text
  • Le tableau input remplace le tableau messages des 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 non input_image)
  • L’URL se trouve dans un objet imbriqué image_url.url (double imbrication)
  • detail réside à l’intérieur de l’objet image_url
  • Le texte utilise le type text (et non input_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: false ou API Chat Completions (native sans état).

Galvenās atziņas

  • 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élange jamais les syntaxes des deux API dans la même requête
  • Vérifie toujours le type d’objet (input_image vs image_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.