Файлы
Загрузите PDF, текст или картинку один раз через /v1/files и ссылайтесь на файл по file_id в запросах к модели. Работает с OpenAI SDK и Anthropic SDK.
Files API принимает файл и выдаёт идентификатор file_…. Вместо того чтобы передавать документ в каждом запросе заново, вы передаёте ссылку на него. Это удобно, когда к одному договору, отчёту или скриншоту нужно задать несколько вопросов.
Ручки одни и те же для обоих SDK: у OpenAI SDK адрес https://api.zveno.ai/v1, у Anthropic SDK — https://api.zveno.ai.
Где хранятся файлы
Файлы, загруженные через /v1/files, хранятся на серверах стороннего поставщика за пределами
России, пока вы не удалите их запросом DELETE /v1/files/{file_id}. Автоматического срока
хранения нет. При обращении модели к файлу его содержимое передаётся поставщику модели.
Не загружайте данные, которые нельзя передавать третьим лицам за рубеж.
Загрузка файла
from openai import OpenAI
client = OpenAI(base_url="https://api.zveno.ai/v1", api_key="<ваш-api-ключ>")
uploaded = client.files.create(file=open("contract.pdf", "rb"), purpose="user_data")
print(uploaded.id) # file_…import fs from 'node:fs'
import OpenAI from 'openai'
const client = new OpenAI({ baseURL: 'https://api.zveno.ai/v1', apiKey: '<ваш-api-ключ>' })
const uploaded = await client.files.create({
file: fs.createReadStream('contract.pdf'),
purpose: 'user_data',
})
console.log(uploaded.id) // file_…import anthropic
client = anthropic.Anthropic(base_url="https://api.zveno.ai", api_key="<ваш-api-ключ>")
uploaded = client.files.upload(
file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)
print(uploaded.id) # file_…curl https://api.zveno.ai/v1/files \
-H "Authorization: Bearer $ZVENOAI_API_KEY" \
-F "file=@contract.pdf" \
-F "purpose=user_data"Параметр purpose нужен только OpenAI SDK: ZvenoAI принимает любое значение и не сохраняет его. Файл появляется в списке только после успешного ответа на загрузку.
Ссылка на файл в запросе
Блок со ссылкой зависит от API, через который вы обращаетесь к модели:
| API | Блок со ссылкой на файл |
|---|---|
/v1/chat/completions | {"type": "file", "file": {"file_id": "file_…"}} |
/v1/responses | {"type": "input_file", "file_id": "file_…"} |
/v1/messages | PDF и текст: {"type": "document", "source": {"type": "file", "file_id": "file_…"}}, картинка: {"type": "image", "source": {"type": "file", "file_id": "file_…"}} |
В примерах client — клиент из раздела выше: OpenAI SDK для Chat Completions и Responses, Anthropic SDK для Messages.
response = client.chat.completions.create(
model="anthropic/claude-sonnet-5.5",
messages=[{
"role": "user",
"content": [
{"type": "file", "file": {"file_id": uploaded.id}},
{"type": "text", "text": "Какие сроки оплаты указаны в договоре?"},
],
}],
)
print(response.choices[0].message.content)response = client.responses.create(
model="anthropic/claude-sonnet-5.5",
input=[{
"role": "user",
"content": [
{"type": "input_file", "file_id": uploaded.id},
{"type": "input_text", "text": "Какие сроки оплаты указаны в договоре?"},
],
}],
)
print(response.output_text)response = client.messages.create(
model="anthropic/claude-sonnet-5.5",
max_tokens=4096,
messages=[{
"role": "user",
"content": [
{"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
{"type": "text", "text": "Какие сроки оплаты указаны в договоре?"},
],
}],
)
for block in response.content:
if block.type == "text":
print(block.text)Запрос со ссылкой на файл идёт только через маршрут, который поддерживает файлы. Если provider.only или provider.ignore исключают такой маршрут, запрос получит 400.
Список, метаданные и удаление
for file in client.files.list():
print(file.id, file.filename, file.bytes)
info = client.files.retrieve("file_…")
client.files.delete("file_…")for file in client.files.list():
print(file.id, file.filename, file.size_bytes)
info = client.files.retrieve_metadata("file_…")
client.files.delete("file_…")curl "https://api.zveno.ai/v1/files?limit=20" -H "Authorization: Bearer $ZVENOAI_API_KEY"
curl https://api.zveno.ai/v1/files/file_… -H "Authorization: Bearer $ZVENOAI_API_KEY"
curl -X DELETE https://api.zveno.ai/v1/files/file_… -H "Authorization: Bearer $ZVENOAI_API_KEY"Список отдаёт файлы от новых к старым. Размер страницы limit — от 1 до 1000: по умолчанию 20 в формате Anthropic и 1000 в формате OpenAI. Курсор — идентификатор последнего файла предыдущей страницы. Его принимают параметры after (OpenAI SDK), after_id и page (Anthropic SDK). SDK листают страницы сами. Разные значения курсора в одном запросе дают 400. Параметры before_id и order=asc не поддерживаются и тоже дают 400.
После удаления запросы со ссылкой на файл получают 404.
Формат ответа
Формат ответа выбирает заголовок anthropic-version. Anthropic SDK отправляет его сам и получает объекты в формате Anthropic: size_bytes, mime_type, downloadable. Запрос без заголовка, например из OpenAI SDK, получает формат OpenAI: bytes, purpose, status. Поля обоих форматов описаны в справочнике API.
Какие файлы подходят
- PDF;
- текст в UTF-8;
- картинки JPEG, PNG, GIF и WebP.
Тип определяется по содержимому файла, а не по расширению. Блок container_upload не поддерживается. Скачать загруженный файл обратно нельзя: ручки /v1/files/{file_id}/content нет. Параметры срока хранения expires_in_seconds и expires_after не поддерживаются и дают 400.
Ограничения
| Ограничение | Значение |
|---|---|
| Размер файла | до 32 МБ |
| Файлов на аккаунт | до 100 |
| Объём на аккаунт | до 500 МБ |
| Частота загрузок | около 30 загрузок в час на аккаунт |
| Доступ к загрузке | после хотя бы одного пополнения баланса деньгами: бонусы и промокоды не считаются |
Чтобы освободить место, удалите ненужные файлы запросом DELETE /v1/files/{file_id}.
Стоимость
Загрузка, список, метаданные и удаление бесплатны. Содержимое файла оплачивается как входные токены модели в каждом запросе, который ссылается на файл. Такой запрос всегда списывается по фактической стоимости, в том числе на бесплатных моделях.
Ошибки
| Код | Когда возникает |
|---|---|
400 | Неподдерживаемый тип файла или параметр, имя файла не в UTF-8 или длиннее 255 байт, превышен лимит аккаунта по числу файлов или объёму, хранилище не приняло файл по содержимому |
401 | Неверный или отключённый ключ |
403 | Загрузка недоступна: баланс аккаунта ещё ни разу не пополнялся деньгами. Бонусы и промокоды не считаются |
404 | Файла нет у этого аккаунта: чужой, удалённый или неизвестный идентификатор |
413 | Файл больше 32 МБ |
429 | Превышен лимит загрузок: около 30 в час на аккаунт. Повторите позже |
502 | Хранилище файлов временно недоступно: файл не сохранён или не удалён. Повторите запрос позже |
503 | Общее хранилище файлов заполнено. Повторите запрос позже |
Общие правила обработки ошибок и повторов — в руководстве Обработка ошибок.