Как работать с медиа

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

В примерах ниже $TEXT_MODEL — переменная окружения с идентификатором модели из GET /api/v1/models. Идентификаторы не зашивают в код: состав каталога меняется. Разбор — в разделе Модели и цены.

Публичные ссылки

Любая прямая ссылка https:// работает как есть — и в image_url.url, и в file.file_url, и во входных параметрах медиа-задачи.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Сравни эти два макета." },
    { "type": "image_url", "image_url": { "url": "https://example.com/a.png" } },
    { "type": "image_url", "image_url": { "url": "https://example.com/b.png" } }
  ]
}

Ссылка должна открываться без заголовков авторизации. Файл за сессионной cookie, за подписью в query-строке с коротким сроком или за IP-allow-list провайдер не скачает: запрос уйдёт, а файл не придёт. Публичные CDN-ссылки вроде url из нашего хранилища подходят.

`data:`-URI с base64

Если ссылка недоступна или файл маленький, вложите содержимое прямо в запрос. Формат — data:<mime>;base64,<данные>. Изображение:

Python

import base64

with open("photo.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

image_url = f"data:image/jpeg;base64,{encoded}"

Аудио — блок input_audio принимает только base64, без data-URI:

Python

import base64

with open("voice.wav", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode()

block = {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "wav"}}

Документ — через file.file_data в виде data-URI:

Python

import base64

with open("contract.pdf", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

block = {
    "type": "file",
    "file": {"filename": "contract.pdf", "file_data": f"data:application/pdf;base64,{encoded}"},
}

Каждый бит base64 стоит примерно 1,33 байта и уезжает в счёт входных токенов. Для файлов от нескольких сотен килобайт и выше переходите на хранилище: ссылка дешевле по трафику, понятнее в логах и не раздувает тело запроса.

Загрузка в хранилище

POST /api/v1/storage/upload — правильный способ для файлов, которые живут дольше одного запроса: изображения пользователей, документы, референсы для генерации. Тело — только multipart/form-data, предел — 100 МБ.

curl -s https://speshu.ai/api/v1/storage/upload \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -F "file=@photo.jpg" \
  -F "asset_type=chat_upload"

import os

import requests

BASE = "https://speshu.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['SPESHU_API_KEY']}"}

with open("photo.jpg", "rb") as f:
    response = requests.post(
        f"{BASE}/storage/upload",
        headers=headers,
        files={"file": ("photo.jpg", f, "image/jpeg")},
        data={"asset_type": "chat_upload"},
        timeout=120,
    )
response.raise_for_status()
asset = response.json()
print(asset["asset_id"], asset["url"])

const form = new FormData();
form.append("file", new Blob([bytes], { type: "image/jpeg" }), "photo.jpg");
form.append("asset_type", "chat_upload");

const response = await fetch("https://speshu.ai/api/v1/storage/upload", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SPESHU_API_KEY}` },
  body: form,
});

const { url } = await response.json();
console.log(url);

Ответ — 201 Created:

{
  "asset_id": "0199...",
  "filename": "photo.jpg",
  "size": 245760,
  "asset_type": "chat_upload",
  "url": "https://cdn.example.com/uploads/<user>/2026/10/02/<uuid>.jpg",
  "mime_type": "image/jpeg"
}

Полный разбор полей и ошибок — на странице Загрузить файл.

Ссылка в запросе

cURL

FILE_URL=$(curl -s https://speshu.ai/api/v1/storage/upload \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -F "file=@photo.jpg" \
  | jq -r '.url')

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TEXT_MODEL"'",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Что на фотографии?"},
        {"type": "image_url", "image_url": {"url": "'"$FILE_URL"'"}}
      ]
    }]
  }'

Ссылка в медиа-задаче

cURL

curl -s https://speshu.ai/api/v1/async/media/tasks \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Добавь крупно надпись SALE поверх баннера",
      "input_urls": ["'"$FILE_URL"'"]
    }
  }'

Имя массива ссылок input_urls поддерживается не у всех моделей. Состав input задаёт поле input_schema в ответе GET /api/v1/media/models, и оно авторитетнее документации.

url из хранилища — обычная публичная ссылка, а не подписанная: срока действия у неё нет, отдавать её можно кому угодно. Если нужна приватная ссылка с ограничением по времени, подписывайте файл по своей схеме — хранилище такое не выдаёт.

Типы блоков ввода

Тип	Поля	Источник данных	Только инлайн
`text`	`text`	—	—
`image_url`	`url`, `detail`	`https://` или `data:`-URI	нет
`input_audio`	`data`, `format` (`wav`, `mp3`)	base64	да
`file`	`filename`, `file_url` или `file_data`	`https://` или `data:`-URI	нет

`file_id` и `asset://`

Этот API не принимает идентификатор файла. Поле file.file_id в схеме есть, но подставить file_id из ответа хранилища, строку вида asset://0199... или что-то подобное нельзя: модель такой файл не увидит. Единственная рабочая ручка — ссылка url из ответа на загрузку, либо data-URI.

Старые версии документации утверждали обратное, и интеграции, построенные на этом, получают отказ. Если файл нужно передать в модель, загрузите его и подставьте url.

Перекодирование при загрузке

Изображения перекодируются без потерь в PNG, если получившийся файл меньше исходного; длинная сторона при этом ограничивается 2000 пикселями. Последствия:

filename в ответе может отличаться от вашего — расширение меняется на .png.
size может оказаться меньше отправленного размера. Это норма, а не ошибка загрузки.
mime_type в ответе отражает уже сохранённый файл.

Не сравнивайте size с размером исходника в логике расчёта квоты — сверяйтесь с тем, что вернул API.

Какие модели принимают изображения

Зрение — не всеобщее свойство. Модель без него отвергает запрос целиком с 400 invalid_request, а не игнорирует картинку молча.

Перед отправкой изображения убедитесь, что выбранная модель принимает зрение. Отбор по названию — эвристика: надёжный признак только один — пробный запрос. Отсортировать каталог по предполагаемым моделям со зрением помогает пример в разделе Модели и цены.

Что дальше

Загрузить файл

Поля формы, квота и ограничения

Создать задачу

Входные параметры и опрос статуса

Запрос чату

Формат сообщений и блоков контента

Модели и цены

Зрение, контекст и стоимость

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Публичные ссылки

`data:`-URI с base64

Загрузка в хранилище

Ссылка в запросе

Ссылка в медиа-задаче

Типы блоков ввода

`file_id` и `asset://`

Перекодирование при загрузке

Какие модели принимают изображения

Что дальше

Загрузить файл

Создать задачу

Запрос чату

Модели и цены

​Публичные ссылки

​data:-URI с base64

​Загрузка в хранилище

​Ссылка в запросе

​Ссылка в медиа-задаче

​Типы блоков ввода

​file_id и asset://

​Перекодирование при загрузке

​Какие модели принимают изображения

​Что дальше

Загрузить файл

Создать задачу

Запрос чату

Модели и цены

Публичные ссылки

`data:`-URI с base64

Загрузка в хранилище

Ссылка в запросе

Ссылка в медиа-задаче

Типы блоков ввода

`file_id` и `asset://`

Перекодирование при загрузке

Какие модели принимают изображения

Что дальше