# Картинки, ролики и речь

Медиа в API моделей принимается в формах OpenAI SDK на том же адресе `https://api.samreshuuu.ru/v1` и с тем же ключом. Модели каждого вида стоят в `GET /v1/models` со своими `architecture.output_modalities` и своей формой `pricing`. Вызов оплачивается с баланса: до работы резервируется цена или верхняя оценка, после ответа списывается то, что получено. Цена каждого вида: цена поставщика плюс наши 20%, в `pricing` она уже с ними.

## Картинки

`POST /v1/images/generations` рисует картинку, `POST /v1/images/edits` рисует по входным картинкам, в форме Images API OpenAI: `client.images.generate(...)` и `client.images.edit(...)` из OpenAI SDK работают со сменой одного базового адреса. Модели картинок стоят в `GET /v1/models` с `architecture.output_modalities: ["image"]`; их `pricing`: рубли за картинку по разрешению (`per_image`) или за мегапиксель результата (`per_megapixel`), отдельно для генерации и для правки. Картинка стоит столько, сколько за неё берёт поставщик, плюс наши 20%.

| Поле | Что значит |
| --- | --- |
| `model`, `prompt` | обязательны |
| `n` | от 1 до 4 картинок; каждая резервируется по своей цене до рисования и списывается, только если пришла |
| `size` | `ШИРИНАxВЫСОТА` или `auto` (у правки кадр первой входной картинки, иначе 1024x1024) |
| `seed` | зерно первой картинки; у следующих оно растёт на единицу |
| `resolution`, `output_format` | свои параметры модели, перечислены в `controls` у `GET /v1/models` |
| `image`, `image[]` | входные картинки правки файлами multipart; в JSON: `images: [{"image_url": "data:image/png;base64,…"}]` |

Ответ: `{"created", "data": [{"b64_json", "seed"}], "output_format", "usage": {"images", "cost", "cost_currency"}}`. Картинки не хранятся, поэтому `response_format: "url"` отклоняется; внешний адрес в `image_url` тоже (пришлите файл). `mask`, `style`, `stream` и параметр, которого у модели нет, отклоняются с `400`, а не пропускаются.

## Ролики

Ролик рендерится минуты, поэтому вызов асинхронный, в форме Videos API OpenAI: `POST /v1/videos` сразу отвечает объектом ролика со `status: "queued"`, `GET /v1/videos/{id}` отвечает, где он сейчас (`queued`, `in_progress`, `completed`, `failed`), `GET /v1/videos/{id}/content` отдаёт готовый MP4. В OpenAI SDK это `client.videos.create(...)`, `client.videos.retrieve(id)` и `client.videos.download_content(id)`. Опрашивайте раз в несколько секунд: частый опрос получает тот же ответ. Модели роликов стоят в `GET /v1/models` с `architecture.output_modalities: ["video"]`; их `pricing.generation`: рубли за секунду (`per_second`) или за ролик (`per_video`) по ступени, ступень называют параметры из `tier_controls`, короче `min_seconds` не считается.

| Поле | Что значит |
| --- | --- |
| `model`, `prompt` | обязательны |
| `seconds` или `duration` | длина ролика в секундах из списка модели |
| `resolution`, `quality`, `aspect_ratio` | свои параметры модели, перечислены в `controls` у `GET /v1/models` |
| `generate_audio` | `true` или `false` для модели со звуком |
| `frame_images` | ключевые кадры: `[{"image_url": {"url": "data:image/png;base64,…"}, "frame_type": "first_frame"}]`, второй с `last_frame`; сколько кадров берёт модель, называет `max_frame_images` |
| `input_reference` | первый кадр файлом multipart (как в OpenAI SDK) или строкой `data:` в JSON |

Ролик резервируется по своей цене до рендера: цена известна заранее по длине и ступени. Списывается она, когда ролик готов, и тогда же появляется `usage.cost`; ролик, который не получился, не стоит ничего. Готовый файл отдаётся до `expires_at` из объекта ролика, потом `GET /v1/videos/{id}/content` отвечает `410 video_expired`. Ролик у нас не хранится: мы передаём файл с площадки поставщика, а он удаляет его в тот же срок. Промпт и кадры тоже не хранятся. Внешний адрес картинки не принимается (пришлите `data:` или файл), `size`, `input_references` (ролик по референсу), `seed`, `callback_url` и `n` больше 1 отклоняются с `400`. Липсинк и ролик персонажа через этот API не продаются.

## Расшифровка речи

`POST /v1/audio/transcriptions` переводит запись в текст, в форме audio transcriptions OpenAI: `client.audio.transcriptions.create(...)` из OpenAI SDK работает со сменой одного базового адреса. Модели речи стоят в `GET /v1/models` с `architecture.input_modalities: ["audio"]` и `output_modalities: ["transcription"]`; их `pricing.transcription.per_minute`: рубли за минуту записи, `max_file_bytes`: самый большой файл, который модель примет; запись длиннее режьте сами. Минута стоит столько, сколько за неё берёт поставщик, плюс наши 20%.

Запрос идёт формой multipart. Формат записи поставщик определяет по расширению имени файла (`meeting.mp3`, `call.ogg`), поэтому имя с расширением обязательно. Если модель речи недоступна, на время сбоя запись расшифровывает заменяющая модель, которую назначает каталог; поле `model` ответа называет ту, что расшифровала, и списание идёт по её цене. На пустой или неуверенный ответ замена не включается. Вызов занимает один запрос в минуте ключа, а токены минуты он не тратит.

```bash
curl https://api.samreshuuu.ru/v1/audio/transcriptions \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
  -F model="openai/whisper-large-v3-turbo" \
  -F file="@meeting.mp3" \
  -F language="ru"
```

```python
import os
from openai import OpenAI

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

with open("meeting.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="openai/whisper-large-v3-turbo",
        file=audio,
        language="ru",
    )
print(transcript.text)
```

| Поле | Что значит |
| --- | --- |
| `file`, `model` | обязательны; запрос идёт формой multipart, файл не больше `max_file_bytes` модели |
| `language` | язык записи кодом ISO-639-1 (`ru`, `en`); без него модель определяет язык сама |
| `prompt` | подсказка: имена, термины, стиль предыдущего отрывка |
| `response_format` | `json` (по умолчанию), `text` или `verbose_json` |
| `timestamp_granularities[]` | `word` и `segment`, только вместе с `verbose_json` |

Ответ `json`: `{"id", "model", "text", "usage": {"type": "duration", "seconds", "cost", "cost_currency": "RUB"}}`. `verbose_json` добавляет `task`, `language`, `duration`, `segments: [{"id", "start", "end", "text"}]` и, если просили `word`, `words: [{"word", "start", "end"}]`. `text` отдаёт голый текст.

До расшифровки на балансе резервируется верхняя оценка по размеру файла: самая низкая разумная скорость записи (6 кбит/с) даёт самую длинную запись, которая может уместиться в файл, по цене самой дорогой модели, к которой может уйти вызов, включая её замену на время сбоя. После ответа списываются услышанные секунды по цене минуты модели, которая ответила, остаток резерва возвращается. Запись и текст не хранятся. `stream: true`, `temperature`, `chunking_strategy`, `include[]`, `known_speaker_names[]` и `known_speaker_references[]`, а также форматы `srt`, `vtt` и `diarized_json` отклоняются с `400`, а не пропускаются.

## Эмбеддинги

`POST /v1/embeddings` переводит текст в векторы, в форме embeddings OpenAI: `client.embeddings.create(...)` из OpenAI SDK работает со сменой одного базового адреса. Модели эмбеддингов стоят в `GET /v1/models` с `architecture.output_modalities: ["embeddings"]` и отдельным списком в `GET /v1/embeddings/models` (без ключа, объекты моделей OpenRouter). У каждой есть `context_length`, `dimensions` (длина вектора модели) и, у моделей, которые можно укоротить, `min_dimensions`; `pricing`: `{"currency": "RUB", "unit_tokens": 1000000, "prompt", "completion": "0"}`, рубли за миллион токенов входа. Токен стоит столько, сколько за него берёт поставщик, плюс наши 20%; сегодняшнюю цену называет `/v1/models`.

```bash
curl https://api.samreshuuu.ru/v1/embeddings \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-embedding-8b",
    "input": ["Сколько дней идёт доставка?", "Доставка по Москве занимает два дня."],
    "dimensions": 1024
  }'
```

| Поле | Что значит |
| --- | --- |
| `model`, `input` | обязательны; `input` это строка или массив до 2048 непустых строк |
| `encoding_format` | `float` (по умолчанию) или `base64`: float32 little-endian, как у OpenAI |
| `dimensions` | длина вектора; только у моделей с `min_dimensions`, от `min_dimensions` до `dimensions` |
| `user` | ваш идентификатор конечного пользователя |

Ответ: `{"object": "list", "id", "model", "data": [{"object": "embedding", "index", "embedding"}], "usage": {"prompt_tokens", "total_tokens", "cost", "cost_currency": "RUB"}}`. Векторы единичной длины: скалярное произведение двух векторов равно их косинусной близости. Модели вроде E5 и Qwen3-Embedding ждут у запроса свою приставку или инструкцию, её пишите в сам текст.

До вызова на балансе резервируется верхняя оценка: токен на каждый байт входа и запас на служебные токены каждой строки. После ответа списываются токены, которые насчитал поставщик, остаток резерва возвращается. Текст и векторы не хранятся. Входы в виде массивов номеров токенов, пустая строка, `input_type` и `dimensions`, которые модель дать не может, отклоняются с `400`, а не пропускаются.

## Переранжирование

`POST /v1/rerank` упорядочивает документы по близости к запросу, в форме rerank OpenRouter, Jina и Cohere v2. Вызова для него в OpenAI SDK нет: пишите запрос сами или через клиент Cohere или Jina с этим базовым адресом. Модели стоят в `GET /v1/models` с `architecture.output_modalities: ["rerank"]`, их `pricing` такой же, как у эмбеддингов: рубли за миллион токенов входа, уже с нашими 20%.

```bash
curl https://api.samreshuuu.ru/v1/rerank \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-reranker-8b",
    "query": "Как вернуть товар?",
    "documents": [
      "Возврат принимаем в течение двух недель с чеком.",
      "Доставка по Москве занимает два дня.",
      {"text": "Деньги за возврат приходят на карту, с которой платили."}
    ],
    "top_n": 2
  }'
```

| Поле | Что значит |
| --- | --- |
| `model`, `query`, `documents` | обязательны; документ это строка или `{"text": "…"}`, не больше 1000 документов |
| `top_n` | сколько лучших вернуть; без него возвращаются все |
| `return_documents` | `true` (по умолчанию) кладёт текст документа в ответ |
| `instruction` | строка задачи для модели Qwen3 (по умолчанию модель считает задачей веб-поиск) |
| `user` | ваш идентификатор конечного пользователя |

Ответ: `{"id", "model", "provider", "results": [{"index", "relevance_score", "document": {"text"}}], "usage": {"total_tokens", "cost", "cost_currency": "RUB"}}`. `results` отсортированы по убыванию `relevance_score`, `index` это номер документа в запросе.

До вызова резервируется верхняя оценка: токен на каждый байт запроса, инструкции и документа каждой пары и запас на служебный промпт модели. После ответа списываются токены, которые насчитал поставщик, остаток возвращается. Запрос и документы не хранятся. Документы с картинками, `max_tokens_per_doc`, `rank_fields` и `max_chunks_per_doc` отклоняются с `400`.

## Синтез речи

`POST /v1/audio/speech` читает текст вслух, в форме audio speech OpenAI: `client.audio.speech.create(...)` из OpenAI SDK работает со сменой одного базового адреса. Модели стоят в `GET /v1/models` с `architecture.output_modalities: ["speech"]`; у каждой `supported_voices` (голоса модели, первый по умолчанию), `max_input_characters` и `pricing`: `{"currency": "RUB", "unit_characters": 1000000, "input_characters"}`, рубли за миллион символов текста, уже с нашими 20%. `qwen/qwen3-tts` говорит на десяти языках, русский среди них.

```bash
curl https://api.samreshuuu.ru/v1/audio/speech \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-tts",
    "input": "Заказ собран и передан в доставку.",
    "voice": "Serena",
    "instructions": "Спокойно и дружелюбно"
  }' \
  --output speech.mp3
```

| Поле | Что значит |
| --- | --- |
| `model`, `input` | обязательны; `input` не длиннее `max_input_characters` модели (4096 символов) |
| `voice` | один из `supported_voices` модели; без него первый |
| `instructions` | тон и манера речи, в том числе темп |
| `response_format` | `mp3` (по умолчанию), `opus`, `flac`, `wav` или `pcm` |
| `user` | ваш идентификатор конечного пользователя |

Ответ это сам звук, `Content-Type` по формату. Расход едет в заголовках: `x-request-id`, `x-usage-characters`, `x-usage-cost` в рублях и `x-usage-cost-currency`; `GET /v1/generation?id=<x-request-id>` отвечает о том же вызове.

Цена известна до вызова: резервируются символы текста, после ответа списываются они же. Текст и звук не хранятся. `speed`, отличный от 1 (просите темп в `instructions`), формат `aac`, `stream_format: "sse"`, свой голос объектом и голос, которого нет у модели (`alloy` и другие голоса OpenAI), отклоняются с `400`.

У эмбеддингов, переранжирования и речи вызов списывается целыми копейками с округлением вверх, как любая трата баланса: короткий вызов стоит копейку, даже если по прайсу поставщика он дешевле. Если поставщик отказал, резерв возвращается целиком. Так же, если ответ нельзя прочитать (нет счёта токенов, векторов или звука): вызов отказывается с `upstream_reply_unreadable` и ничего не стоит.
