input_image vs image_url: Οι δύο συντάξεις
Σε αυτήν τη σελίδα
Δύο API, δύο συντάξεις
Η xAI προσφέρει δύο τελικά σημεία (endpoints) για αλληλεπίδραση με το Grok, και το καθένα χρησιμοποιεί διαφορετική σύνταξη για την αποστολή εικόνων. Η κατανόηση αυτών των διαφορών είναι απαραίτητη για τη συγγραφή σωστού κώδικα και την αποφυγή εκνευριστικών σφαλμάτων.
Responses API: input_image (συνιστάται)
Το Responses API είναι το νέο κύριο τελικό σημείο της xAI. Οι νέες λειτουργίες προστίθενται εδώ πρώτες. Αυτό είναι το API που πρέπει να προτιμάτε για κάθε νέο έργο.
Σύνταξη
{
"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."
}
]
}
Χαρακτηριστικά
- Ο τύπος είναι
input_image(όχιimage_url) - Το URL ή το Data URI τοποθετείται απευθείας στο
image_url(χωρίς ένθετο αντικείμενο) - Το
detailβρίσκεται στο ίδιο επίπεδο με τοimage_url - Το κείμενο χρησιμοποιεί τον τύπο
input_text - Ο πίνακας
inputαντικαθιστά τον πίνακαmessagesαπό το 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": "Describe this image."
}
],
store=False
)
print(response.output_text)
Chat Completions API: image_url (παλαιό)
Το Chat Completions API είναι το παλαιό τελικό σημείο, το οποίο διατηρείται για συμβατότητα με τα υπάρχοντα SDK της OpenAI. Εάν μεταφέρετε κώδικα γραμμένο για την OpenAI, αυτό το API διευκολύνει τη μετάβαση.
Σύνταξη
{
"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."
}
]
}
]
}
Χαρακτηριστικά
- Ο τύπος είναι
image_url(όχιinput_image) - Το URL βρίσκεται μέσα σε ένα ένθετο αντικείμενο
image_url.url(διπλή ένθεση) - Το
detailβρίσκεται μέσα στο αντικείμενοimage_url - Το κείμενο χρησιμοποιεί τον τύπο
text(όχιinput_text) - Τα μηνύματα έχουν έναν
role(system, user, assistant)
Python με OpenAI SDK
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)
Πίνακας σύγκρισης
| Πτυχή | API Responses | Chat Completions |
|---|---|---|
| Κατάσταση | Κύριο (συνιστάται) | Παλαιό (συμβατότητα) |
| Τύπος εικόνας | input_image | image_url |
| Τύπος κειμένου | input_text | text |
| URL εικόνας | image_url: "..." | image_url.url: "..." |
| Διαχείριση κατάστασης | Με κατάσταση (previous_response_id) | Χωρίς κατάσταση (επαναποστολή όλων) |
| Αποθήκευση | store: true/false | Όχι (χωρίς κατάσταση) |
| Εργαλεία διακομιστή | web_search, x_search, code_interpreter | Περιορισμένα |
Συχνά σφάλματα σύνταξης
Σφάλμα 1: Ανάμειξη μορφών
# ΛΑΘΟΣ — Σύνταξη Chat Completions στο Responses API
input=[
{"type": "image_url", "image_url": {"url": "..."}} # Όχι!
]
# ΣΩΣΤΟ — Σύνταξη Responses API
input=[
{"type": "input_image", "image_url": "..."} # Ναι!
]
Σφάλμα 2: Ξέχνημα της ένθετης δομής στο Chat Completions
# ΛΑΘΟΣ — Άμεσο URL στο Chat Completions
{"type": "image_url", "image_url": "https://..."} # Όχι!
# ΣΩΣΤΟ — Ένθετο αντικείμενο
{"type": "image_url", "image_url": {"url": "https://..."}} # Ναι!
Σφάλμα 3: Χρήση του “text” αντί του “input_text”
# ΛΑΘΟΣ — Τύπος "text" στο Responses API
input=[
{"type": "text", "text": "Describe."} # Όχι!
]
# ΣΩΣΤΟ
input=[
{"type": "input_text", "text": "Describe."} # Ναι!
]
Πότε να χρησιμοποιείτε κάθε API
- Νέο έργο: χρησιμοποιήστε το Responses API. Σας παρέχει πρόσβαση στις τελευταίες λειτουργίες και στην αποθήκευση συνομιλιών.
- Μετάβαση από την OpenAI: ξεκινήστε με το Chat Completions για να ελαχιστοποιήσετε τις αλλαγές στον κώδικα και, στη συνέχεια, μεταβείτε σταδιακά στο Responses API.
- Ευαίσθητες εικόνες: Responses API με
store: falseή Chat Completions API (εγγενώς χωρίς κατάσταση).
Βασικά σημεία
- Το Responses API χρησιμοποιεί
input_image+input_text, ενώ το Chat Completions API χρησιμοποιείimage_url+text. - Η δομή του URL διαφέρει: άμεση στο Responses, ένθετη στο Chat Completions.
- Το Responses API είναι η συνιστώμενη επιλογή για κάθε νέα ανάπτυξη.
- Μην αναμειγνύετε ποτέ συντάξεις και από τα δύο API στο ίδιο αίτημα.
- Ελέγχετε πάντα τον τύπο του αντικειμένου (
input_imagevsimage_url) για να αποφύγετε σιωπηλά σφάλματα.
Δοκιμάστε τις γνώσεις σας
Όραμα API της xAI: μορφές, tokens, συντάξεις—είναι όλα στη θέση τους;
1. Πώς στέλνετε μια εικόνα στο API;
Απάντηση: Μέσω URL ή Base64, σε ένα μήνυμα μικτού περιεχομένου—σεβόμενοι την τεκμηριωμένη μορφή και τους περιορισμούς μεγέθους.
2. Τι ελέγχει η παράμετρος detail (auto, low, high);
Απάντηση: Τη λεπτομέρεια ανάλυσης και το κόστος: το low εξοικονομεί tokens για περιπτώσεις χρήσης χαμηλής ανάλυσης, το high μεγιστοποιεί την ακρίβεια (OCR, λεπτές λεπτομέρειες), το auto αφήνει το API να αποφασίσει.
3. Πώς υπολογίζεται το κόστος μιας εικόνας;
Απάντηση: Σε tokens εικόνας—από 256 έως 1792 ανάλογα με την ανάλυση και τη λεπτομέρεια: η προσαρμογή του μεγέθους των εικόνων και του επιπέδου λεπτομέρειας είναι ο πρώτος μοχλός βελτιστοποίησης.
4. Τι επιτρέπει η σύγκριση πολλαπλών εικόνων;
Απάντηση: Την αποστολή πολλαπλών εικόνων σε ένα μόνο αίτημα και τη λογική επεξεργασία τους—διαφορές, εξελίξεις, συνοχή—χωρίς όριο στον αριθμό των εικόνων ανά αίτημα.
5. input_image ή image_url: ποιο να επιλέξετε;
Απάντηση: Το input_image είναι η σύγχρονη σύνταξη του Responses API· το image_url παραμένει ως παλαιό του Chat Completions—για νέο κώδικα, η σύγχρονη σύνταξη είναι υποχρεωτική.
Καλή μορφή, καλή λεπτομέρεια, καλή σύνταξη: το όραμα καθοδηγείται όπως το κείμενο—μέχρι το τελευταίο token.