Управление на файловете: списък, извличане, изтриване
На тази страница
Какво се случва след стотния качен файл
Качването на файл отнема три секунди; откриването на този, който сте изпратили преди шест седмици, отнема много повече време, ако не сте планирали предварително. След първоначалните тестове акаунтът натрупва десетки, а след това и стотици документи. Някои са остарели, други са дублирани, а трети се използват от все още работещи приложения. Files API предоставя три операции за управление на този инвентар: списък, извличане и изтриване. Те изглеждат второстепенни, докато обемът е малък, но по-късно стават незаменими.
Инвентаризация
GET /v1/files връща всички файлове, качени във Вашия акаунт:
curl https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY"
Отговорът е分页иран списък, като всеки запис повтаря метаданните, видени при качването:
{
"object": "list",
"data": [
{
"id": "file_abc123",
"object": "file",
"bytes": 2458901,
"created_at": 1710000000,
"filename": "rapport-annuel.pdf",
"purpose": "assistants"
},
{
"id": "file_def456",
"object": "file",
"bytes": 15230,
"created_at": 1710100000,
"filename": "données-clients.csv",
"purpose": "assistants"
}
]
}
Този изглед решава три много конкретни ситуации: възстановяване на file_id, което не сте запазили по време на качването; проверка на действителния размер на документ, който изглежда необичайно тежък; и откриване на кандидати за изтриване чрез сортиране по created_at. Това е също единственото място, където ще видите с един поглед, че един и същ отчет е изпращан три пъти под три различни имена.
Проверка на конкретен файл
Когато вече знаете идентификатора, GET /v1/files/{file_id} заявява един единствен документ:
curl https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
Вие извличате същата информация като при качването: идентификатор, име, размер, дата на създаване и цел. Най-полезното приложение на това обаждане е превантивно. Преди стартиране на процес, който се позовава на file_id, съхраняван от дълго време във Вашата база данни, една проверка, отнемаща няколко милисекунди, Ви спестява грешка посред верига от таксувани заявки.
Изтриване и какво да проверите преди това
Изтриването се извършва с DELETE /v1/files/{file_id}, а отговорът потвърждава операцията:
curl -X DELETE https://api.x.ai/v1/files/file_abc123 \
-H "Authorization: Bearer $XAI_API_KEY"
{
"id": "file_abc123",
"object": "file",
"deleted": true
}
Преди да натиснете спусъка, са необходими две проверки. Първо, файлът може да бъде препратен в колекция – концепция, която ще разгледаме подробно в следващите уроци. Изтриването му чрез Files API не го премахва автоматично от колекцията, което оставя мъртва препратка във Вашия индекс: първо го премахнете от колекцията, след това от хранилището. На второ място, файлът може да се използва от активни работни потоци; всяко приложение, което пази този file_id в своята база данни, ще получи грешки веднага щом изтриването бъде извършено, често в продукционна среда и рядко докато наблюдавате логовете.
Поддържайте хранилището си чисто
Именуването е Вашият първи инструмент за управление, защото оригиналното име се запазва в метаданните и представлява единственият четим маркер в списък от сто записа. rapport-q1-2026.pdf ще означава нещо за Вас след осем месеца; document.pdf – никога. Същото разсъждение важи за api-specs-v2.json спрямо data.json. Направете от това навик, когато подготвяте файла на Вашия диск, а не по време на качването: именно локалното име се предава.
Качените файлове остават съхранени за неопределено време, без автоматично изтичане на срока. Една тримесечна rutina за почистване е достатъчна, за да избегнете отклонения, в три стъпки:
- Избройте файловете си с
GET /v1/files - Идентифицирайте тези, които вече не се използват, по дата на създаване или име
- Изтрийте ги с
DELETE /v1/files/{file_id}
Три кода за грешки възникват при тези операции и се диагностицират незабавно. 404 сигнализира несъществуващ или вече изтрит файл, типичен случай при скрипт за почистване, стартиран два пъти. 401 произтича от липсващ или невалиден API ключ, често променлива на средата, която не е заредена в текущата обвивка. 413 показва, че файлът надвишава разрешените 48 MB и възниква при качване, а не по време на управлението.
Ключови изводи
GET /v1/filesизброява всички Ваши файлове с техните метаданниGET /v1/files/{id}извлича конкретен файлDELETE /v1/files/{id}изтрива необратимо файл- Именувайте файловете си изрично, за да улесните управлението
- Проверете зависимостите (колекции, работни потоци) преди изтриване