Μεταφόρτωση αρχείων με το Files API
Σε αυτήν τη σελίδα
Από την αντιγραφή-επικόλληση στα εγγενή έγγραφα
Πιθανότατα έχετε επικολλήσει δεκαπέντε σελίδες μιας αναφοράς σε ένα prompt ελπίζοντας ότι η διάταξη θα διατηρηθεί. Αυτό δεν συμβαίνει ποτέ: οι στήλες των πινάκων μπερδεύονται και το μοντέλο καταλήγει να συλλογίζεται πάνω σε ένα ακατάληπτο κείμενο. Το Files API της xAI λύνει ακριβώς αυτό το πρόβλημα. Στέλνετε το πρωτότυπο έγγραφο, η xAI το αναλύει διακομιστικά (server-side) και το Grok εργάζεται πάνω στο περιεχόμενο διατηρώντας τη δομή, τους πίνακες και τα διαχωριστικά ενοτήτων.
Ο μηχανισμός αυτός ενσωματώνεται σε ένα μόνο endpoint, το POST /v1/files. Στέλνετε το αρχείο σας ως multipart/form-data με την παράμετρο purpose ορισμένη σε "assistants" και το API επιστρέφει ένα μοναδικό αναγνωριστικό που ονομάζεται file_id. Αυτό το αναγνωριστικό γίνεται το κλειδί για ό,τι κάνετε στη συνέχεια: ερώτηση στο έγγραφο, έλεγχος των μεταδεδομένων του, διαγραφή του ή προσθήκη του σε μια συλλογή.
Η πρώτη σας μεταφόρτωση
Λάβετε μια ετήσια αναφορά σε μορφή PDF που βρίσκεται στον δίσκο σας. Το αίτημα μεταφόρτωσης δεν είναι JSON αλλά multipart/form-data, γεγονός που εξηγεί τη χρήση της σύνταξης -F αντί της -d:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Η απόκριση φτάνει σε λίγα δευτερόλεπτα και περιέχει το αναγνωριστικό του αρχείου μαζί με τα χαρακτηριστικά του:
{
"id": "file_abc123xyz",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "annual-report.pdf",
"purpose": "assistants"
}
Αυτό το file_id—εδώ το file_abc123xyz—είναι η μόνιμη αναφορά σας στο έγγραφο. Σημειώστε το μόλις λάβετε την απόκριση: ένα χαμένο αναγνωριστικό σημαίνει ένα ορφανό αρχείο που καταναλώνει ποσόστωση χωρίς να είναι usable.
Παράμετροι και πιστοποίηση
Μόνο δύο παράμετροι, και οι δύο απαιτούμενες:
- file: Το δυαδικό περιεχόμενο του αρχείου, αποστελλόμενο ως multipart. Το μέγιστο μέγεθος είναι 48 MB.
- purpose: Πάντα
"assistants", η μοναδική αποδεκτή τιμή μέχρι σήμερα. Υποδεικνύει ότι το αρχείο θα χρησιμοποιηθεί για αλληλεπιδράσεις με το μοντέλο.
Θα φτάσετε στο όριο των 48 MB γρηγορότερα από όσο νομίζετε: μια εξαγωγή ημερολογίου μίας ημέρας ή η πλήρης τεκμηρίωση προϊόντος συχνά το ξεπερνούν. Σε αυτή την περίπτωση, διαιρέστε την πηγή σας σε πολλά συνεκτικά αρχεία αντί να τα περικόπτετε αυθαίρετα· θα τα βρείτε όλα στην ίδια συλλογή αργότερα.
Όσον αφορά την πιστοποίηση, κάθε αίτημα στο Files API φέρει το τυπικό κλειδί API σας στην κεφαλίδα Authorization: Bearer. Να έχετε υπόψη σας από τώρα ότι αυτό το κλειδί δεν είναι το Management API Key: εκείνο, που προορίζεται για συλλογές, θα παρουσιαστεί αργότερα στο μάθημα και συχνά συγχέεται με το πρώτο κατά τις αρχικές προσπάθειες.
Χρήση του αρχείου
Το μεταφορτωμένο αρχείο είναι άχρηστο εάν δεν το αναφέρετε σε ένα αίτημα. Αυτός είναι ο ρόλος του μπλοκ input_file στο Responses API, το οποίο συνοδεύετε με μια οδηγία ελεύθερου κειμένου:
{
"model": "grok-4.5",
"input": [
{
"type": "input_file",
"file_id": "file_abc123xyz"
},
{
"type": "input_text",
"text": "Συνοψίστε τα βασικά σημεία αυτού του εγγράφου."
}
]
}
Το Grok λαμβάνει το αρχείο, ενεργοποιεί αυτόματα το εργαλείο attachment_search διακομιστικά, εξάγει τα σχετικά αποσπάσματα και συντάσσει την απάντησή του βάσει αυτών. Δεν απαιτείται χειροκίνητη ενεργοποίηση και δεν χρειάζεται να προστεθούν πρόσθετες παράμετροι: η παρουσία ενός input_file αρκεί για να ενεργοποιηθεί ολόκληρη η αλυσίδα. Κάθε κλήση συνημμένου χρεώνεται με $10 ανά 1.000, καθιστώντας μια μοναδική μεταφόρτωση που ερωτάται δέκα φορές πιο οικονομική από δέκα μεταφορτώσεις του ίδιου εγγράφου.
Τιμολόγηση στις 5 Αυγούστου 2026 — οι τιμές αλλάζουν τακτικά: πριν από οποιοδήποτε υπολογισμό προϋπολογισμού, ελέγξτε το τρέχον τιμολόγιο στην επίσημη σελίδα μοντέλων και τιμολόγησης της xAI.
Βασικά σημεία
- Το endpoint
POST /v1/filesδέχεται αρχεία έως 48 MB σε μορφήmultipart/form-data - Η παράμετρος
purposeπρέπει να είναι"assistants" - Το επιστρεφόμενο
file_idείναι η αναφορά σας για όλες τις επόμενες εργασίες - Το εργαλείο
attachment_searchενεργοποιείται αυτόματα όταν ένα αρχείο αναφέρεται σε ένα αίτημα - Το κόστος είναι $10 ανά 1.000 κλήσεις συνημμένων