Файлы

Files API — хранилище файлов вашего аккаунта. Файл загружается один раз, получает идентификатор вида rai_file_… и дальше указывается в запросах вместо содержимого: не нужно каждый раз кодировать его в base64 и пересылать в теле запроса.

Отдельной платы за хранение нет.

Загрузка файла

Файл отправляется на /api/v1/files запросом multipart/form-data, поле file:

curl https://routerai.ru/api/v1/files \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -F "file=@photo.png"

import os
import requests

with open("photo.png", "rb") as f:
    response = requests.post(
        "https://routerai.ru/api/v1/files",
        headers={"Authorization": f"Bearer {os.environ['ROUTERAI_API_KEY']}"},
        files={"file": f},
    )

file_id = response.json()["id"]

Ответ — метаданные файла:

{
  "id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW",
  "type": "file",
  "filename": "photo.png",
  "mime_type": "image/png",
  "size_bytes": 184320,
  "created_at": "2026-10-13T10:30:25.818Z",
  "downloadable": false
}

Правила и лимиты

Тип файла определяется по содержимому, а не по расширению и не по заголовку Content-Type: PNG с именем report.txt сохранится как image/png.

Файл принадлежит аккаунту ключа. В команде квота общая, а видимость файлов зависит от роли:

• участник видит, использует в запросах и удаляет только файлы, загруженные им самим — своими ключами или в личном кабинете;
• администратор команды видит и может использовать или удалить файлы всех участников;
• ключ уровня команды, не привязанный к участнику, работает как ключ администратора.

Использование в запросах

Укажите идентификатор файла в блоке содержимого сообщения. Форма блока зависит от API.

Какие файлы можно передавать

Документы обрабатываются так же, как при отправке в base64 — подробности и выбор способа разбора PDF описаны в гайде «Работа с PDF».

Chat Completions

curl https://routerai.ru/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "google/gemini-4-argon",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Что изображено на этой картинке?"
          },
          {
            "type": "file",
            "file": {
              "file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"
            }
          }
        ]
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://routerai.ru/api/v1",
    api_key=os.environ["ROUTERAI_API_KEY"],
)

completion = client.chat.completions.create(
    model="google/gemini-4-argon",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Что изображено на этой картинке?"},
                {"type": "file", "file": {"file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"}},
            ],
        }
    ],
)

print(completion.choices[0].message.content)

Responses

Для изображений подходят оба типа блока — input_image и input_file, для документов и текста — только input_file:

curl https://routerai.ru/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "google/gemini-4-argon",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Что изображено на этой картинке?"
          },
          {
            "type": "input_image",
            "file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"
          }
        ]
      }
    ]
  }'

Messages

Блок image или document с источником типа file. Изображение можно передать в любом из них, документ и текст — только в document:

curl https://routerai.ru/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Что изображено на этой картинке?"
          },
          {
            "type": "image",
            "source": {
              "type": "file",
              "file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"
            }
          }
        ]
      }
    ]
  }'

Аудио

Аудиофайл передаётся тем же блоком file (в Responses — input_file) либо блоком input_audio с идентификатором вместо содержимого. Формат указывать не нужно — он берётся из файла:

{
  "type": "input_audio",
  "input_audio": {
    "file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"
  }
}

В Messages аудио на входе не поддерживается — такой запрос вернёт ошибку 400. Набор форматов зависит от модели: например, аудиомодели OpenAI принимают только WAV и MP3. Подробнее — в гайде «Аудио».

Для расшифровки речи идентификатор указывается в input_audio вместо data и format:

curl https://routerai.ru/api/v1/audio/transcriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  -d '{
    "model": "google/gemini-3.5-transcribe",
    "input_audio": {
      "file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"
    }
  }'

В запросе multipart/form-data вместо поля file передаётся поле file_id.

Генерация изображений

В запросе к /api/v1/images загруженную картинку можно указать как исходную в input_references и как маску в mask:

{
  "model": "openai/gpt-image-2.5-sunburst",
  "prompt": "Замени фон на закат",
  "input_references": [
    {"type": "file", "file": {"file_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"}}
  ]
}

Здесь подходят только изображения. Требования к формату и размеру картинки зависят от модели — см. гайд «Генерация изображений».

Что важно знать

• Экономии токенов нет. RouterAI подставляет содержимое файла в запрос к провайдеру, модель каждый раз получает и оплачивает файл целиком — столько же токенов, сколько при отправке того же файла в base64. Идентификатор избавляет только от пересылки содержимого в теле запроса.
• Файл не привязан к провайдеру. Один и тот же идентификатор работает с любой подходящей моделью во всех трёх API. Выбор провайдера и переключение на резервного работают как обычно.
• Лимиты запроса: до 20 файлов, изображение до 20 МБ, документ, текстовый или аудиофайл до 25 МБ, все вместе до 32 МБ.
• Документы и аудио — только в сообщении пользователя. Внутри результата инструмента (tool_result, function_call_output) по идентификатору можно передать только изображение.
• Идентификаторы других сервисов не подходят. Значения вида file-… и file_…, полученные в Files API OpenAI или Anthropic, вернут ошибку 400: загрузите файл в RouterAI и используйте его идентификатор.
• В image_url идентификатор файла указывать нельзя — только в блоках, перечисленных выше. Это относится и к input_references.

Список файлов

curl "https://routerai.ru/api/v1/files?limit=20" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY"

Файлы возвращаются от новых к старым:

{
  "data": [
    {
      "id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW",
      "type": "file",
      "filename": "photo.png",
      "mime_type": "image/png",
      "size_bytes": 184320,
      "created_at": "2026-10-13T10:30:25.818Z",
      "downloadable": false
    }
  ],
  "has_more": true,
  "first_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW",
  "last_id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW"
}

Пока has_more равно true, запрашивайте следующую страницу с after, равным last_id предыдущего ответа.

Метаданные и удаление

# Метаданные одного файла
curl https://routerai.ru/api/v1/files/rai_file_jHl6fK2WxH3qkGu2uwnPYtyW \
  -H "Authorization: Bearer $ROUTERAI_API_KEY"

# Удаление
curl -X DELETE https://routerai.ru/api/v1/files/rai_file_jHl6fK2WxH3qkGu2uwnPYtyW \
  -H "Authorization: Bearer $ROUTERAI_API_KEY"

Ответ на удаление:

{
  "id": "rai_file_jHl6fK2WxH3qkGu2uwnPYtyW",
  "type": "file",
  "deleted": true
}

Удаление необратимо и сразу освобождает место в хранилище. Запросы с идентификатором удалённого файла получают ошибку 404.

Ошибки

Ошибки приходят в формате {"error": {"message": "…", "code": 400}}. Отклонённый запрос к модели не тарифицируется.