Качване на файлове чрез Files API
На тази страница
От копиране-поставяне до нативни документи
Вероятно сте поставяли петнадесет страници от доклад в подсказка, надявайки се, че оформлението ще се запази. Това никога не се случва: колоните в таблиците се объркват и моделът започва да разсъждава върху неструктуриран текст. Files API на xAI решава точно този проблем. Изпращате оригиналния документ, xAI го анализира от страната на сървъра, а 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 – е Вашата постоянна препратка към документа. Запишете го веднага щом получите отговора: загубеният идентификатор означава осиротял файл, който консумира квота, без да може да бъде използван.
Параметри и удостоверяване
Само два параметъра, и двата задължителни:
- 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 на 1000, което прави едно качване, заявено десет пъти, по-рентабилно от десет качвания на един и същи документ.
Цени към 5 август 2026 г. – цените се променят редовно: преди всяко изчисление на бюджета проверете текущата тарифа на официалната страница за модели и цени на xAI.
Ключови изводи
- Крайната точка
POST /v1/filesприема файлове до 48 MB във форматmultipart/form-data - Параметърът
purposeтрябва да бъде"assistants" - Върнатият
file_idе Вашата препратка за всички последващи операции - Инструментът
attachment_searchсе активира автоматично, когато файл е споменат в заявка - Цената е $10 на 1000 повиквания за прикачени файлове