Μορφή περιεχομένου: απλή συμβολοσειρά και πίνακας αντικειμένων
Σε αυτήν τη σελίδα
Δύο μορφές για το πεδίο content
Το πεδίο content κάθε μηνύματος δέχεται δύο διαφορετικές μορφές στο API Chat Completions της xAI. Η επιλογή εξαρτάται από το τι στέλνετε στο μοντέλο: απλό κείμενο ή πολυτροπικό περιεχόμενο (κείμενο + εικόνες).
Μορφή συμβολοσειράς: η πιο συνηθισμένη περίπτωση
Για μηνύματα που περιέχουν αποκλειστικά κείμενο, το πεδίο content είναι μια απλή συμβολοσειρά:
{
"role": "user",
"content": "Explain how a transformer works."
}
Αυτή είναι η μορφή που θα χρησιμοποιείτε στη συντριπτική πλειοψηφία των περιπτώσεων. Είναι απλή, ευανάγνωστη και επαρκής για όλες τις αλληλεπιδράσεις κειμένου με το Grok.
Για το μήνυμα system, η μορφή συμβολοσειράς χρησιμοποιείται σχεδόν πάντα:
{
"role": "system",
"content": "You are a software architecture expert. Respond in English with Python code examples."
}
Μορφή πίνακα: πολυτροπικό περιεχόμενο
Όταν χρειάζεται να στείλετε εικόνες μαζί με κείμενο, το πεδίο content γίνεται ένας πίνακας αντικειμένων με τύπο. Κάθε αντικείμενο διαθέτει ένα πεδίο type που υποδεικνύει τη φύση του.
{
"role": "user",
"content": [
{
"type": "text",
"text": "What does this image show?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/photo.jpg",
"detail": "high"
}
}
]
}
Διαθέσιμοι τύποι αντικειμένων
Ο πίνακας περιεχομένου δέχεται δύο τύπους αντικειμένων:
text: ένα μπλοκ κειμένου με την ιδιότηταtextimage_url: μια αναφορά σε εικόνα με την ιδιότηταimage_url
Μπορείτε να συνδυάσετε όσα αντικείμενα χρειάζεστε σε ένα μόνο μήνυμα. Για παράδειγμα, για να ζητήσετε από το μοντέλο να συγκρίνει δύο εικόνες:
{
"role": "user",
"content": [
{"type": "text", "text": "Compare these two architecture diagrams."},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v1.png"}},
{"type": "image_url", "image_url": {"url": "https://example.com/schema-v2.png"}}
]
}
Η παράμετρος detail για τις εικόνες
Κάθε αντικείμενο image_url δέχεται μια προαιρετική παράμετρο detail που ελέγχει την ανάλυση της ανάλυσης:
auto: το μοντέλο επιλέγει αυτόματα το επίπεδο λεπτομέρειας (προεπιλεγμένη τιμή)low: γρήγορη και οικονομική ανάλυση, επαρκής για απλές εικόνες (εικονίδια, βασικά διαγράμματα)high: λεπτομερής ανάλυση, συνιστάται για πολύπλοκες εικόνες (έγγραφα, φωτογραφίες, διεπαφές)
{
"type": "image_url",
"image_url": {
"url": "https://example.com/document-scan.jpg",
"detail": "high"
}
}
Η επιλογή του επιπέδου λεπτομέρειας επηρεάζει άμεσα τον αριθμό των tokens που καταναλώνονται και, κατά συνέπεια, το κόστος του αιτήματος.
Πότε να χρησιμοποιείτε κάθε μορφή;
Ο κανόνας είναι απλός:
- Μόνο κείμενο → μορφή συμβολοσειράς (πιο απλή, πιο ευανάγνωστη)
- Κείμενο + εικόνες → μορφή πίνακα (απαραίτητη για πολυτροπικά δεδομένα)
- Μόνο εικόνες → μορφή πίνακα με αντικείμενα αποκλειστικά
image_url
Μια μορφή πίνακα με ένα μόνο αντικείμενο text είναι λειτουργικά ισοδύναμη με τη μορφή συμβολοσειράς, αλλά περιττά verbose:
// Ισοδύναμο αλλά περιττά πολύπλοκο
{"content": [{"type": "text", "text": "Hello"}]}
// Προτιμήστε αυτή τη μορφή
{"content": "Hello"}
Τεχνικοί περιορισμοί για τις εικόνες
Πριν στείλετε εικόνες στο API της xAI, λάβετε υπόψη τα εξής όρια:
- Μέγιστο μέγεθος: 20 MiB ανά εικόνα
- Αποδεκτές μορφές: Μόνο JPG, JPEG, PNG (όχι GIF, WebP ή SVG)
- Πλήθος: κανένα όριο στον αριθμό των εικόνων ανά αίτημα
- Συμβατά μοντέλα: μόνο grok-4.5 και νεότερες εκδόσεις
Οι εικόνες μπορούν να παρέχονται μέσω δημόσιας URL ή κωδικοποιημένες σε base64 εντός της ίδιας της URL (μορφή data:image/jpeg;base64,...).
Βασικά σημεία
- Το πεδίο
contentδέχεται μια απλή συμβολοσειρά (κείμενο) ή έναν πίνακα αντικειμένων (πολυτροπικό) - Η μορφή πίνακα χρησιμοποιεί αντικείμενα με πεδίο
type:"text"ή"image_url" - Η παράμετρος
detail(auto,low,high) ελέγχει την ανάλυση ανάλυσης για τις εικόνες - Οι εικόνες περιορίζονται στα 20 MiB σε μορφή JPG/PNG και απαιτούν grok-4.5 ή νεότερη έκδοση
- Χρησιμοποιείτε τη μορφή συμβολοσειράς όταν στέλνετε μόνο κείμενο· είναι πιο ευανάγνωστη και απλή