ZvenoAI
Руководства

Файлы

Загрузите 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/messagesPDF и текст: {"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Общее хранилище файлов заполнено. Повторите запрос позже

Общие правила обработки ошибок и повторов — в руководстве Обработка ошибок.

On this page