Премини към основното съдържание
Български— Изберете език
Меню

Качване на файлове чрез Files API

Урок 1 от 16 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. От копиране-поставяне до нативни документи
  2. Първото Ви качване
  3. Параметри и удостоверяване
  4. Използване на файла
  5. Ключови изводи

От копиране-поставяне до нативни документи

Вероятно сте поставяли петнадесет страници от доклад в подсказка, надявайки се, че оформлението ще се запази. Това никога не се случва: колоните в таблиците се объркват и моделът започва да разсъждава върху неструктуриран текст. Files API на xAI решава точно този проблем. Изпращате оригиналния документ, xAI го анализира от страната на сървъра, а Grok работи със съдържание, при което структурата, таблиците и разделенията на секции са запазени.

Механизмът се събира в един единствен крайна точка (endpoint), POST /v1/files. Изпращате файла си като multipart/form-data с параметър purpose, зададен на "assistants", а API връща уникален идентификатор, наречен file_id. Този идентификатор става ключът за всичко, което правите след това: заявка към документа, проверка на метаданните му, изтриването му или добавянето му към колекция.

48 MB
Максимален размер на файл
POST
HTTP метод за качване
$10
На 1000 повиквания
Auto
Активиране на attachment_search

Първото Ви качване

Вземете годишен отчет в 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 повиквания за прикачени файлове