# Pictures, videos and speech

Media on the Model API is taken in the OpenAI SDK forms at the same address, `https://api.samreshuuu.ru/v1`, with the same key. Each kind's models are in `GET /v1/models` with their own `architecture.output_modalities` and their own `pricing` shape. A call is paid from the balance: before the work its price or an upper estimate is held, after the answer what was delivered is charged. Each kind's price is the vendor's price plus our 20%, and `pricing` already includes it.

## Images

`POST /v1/images/generations` draws a picture, `POST /v1/images/edits` draws from input pictures, in OpenAI's Images API form: the OpenAI SDK's `client.images.generate(...)` and `client.images.edit(...)` work with only the base URL changed. The image models are in `GET /v1/models` with `architecture.output_modalities: ["image"]`; their `pricing` is in roubles per picture by resolution (`per_image`) or per megapixel of output (`per_megapixel`), for generation and for edit apart. A picture costs what the vendor bills for it, plus our 20%.

| Field | Meaning |
| --- | --- |
| `model`, `prompt` | required |
| `n` | 1 to 4 pictures; each is held at its price before it is drawn and charged only if it came back |
| `size` | `WIDTHxHEIGHT` or `auto` (the first input's frame on an edit, else 1024x1024) |
| `seed` | the first picture's seed; the next ones count up from it |
| `resolution`, `output_format` | the model's own controls, listed under `controls` in `GET /v1/models` |
| `image`, `image[]` | an edit's input pictures as multipart files; in JSON, `images: [{"image_url": "data:image/png;base64,…"}]` |

The answer is `{"created", "data": [{"b64_json", "seed"}], "output_format", "usage": {"images", "cost", "cost_currency"}}`. Pictures are not stored, so `response_format: "url"` is refused; a remote `image_url` is refused too (send the file). `mask`, `style`, `stream` and a control the model does not take are refused with `400`, not ignored.

## Videos

A clip renders for minutes, so the call is asynchronous, in OpenAI's Videos API form: `POST /v1/videos` answers at once with the video object at `status: "queued"`, `GET /v1/videos/{id}` answers where it stands (`queued`, `in_progress`, `completed`, `failed`), `GET /v1/videos/{id}/content` returns the finished MP4. In the OpenAI SDK these are `client.videos.create(...)`, `client.videos.retrieve(id)` and `client.videos.download_content(id)`. Poll every few seconds: a faster poll gets the same answer. The video models are in `GET /v1/models` with `architecture.output_modalities: ["video"]`; their `pricing.generation` is in roubles per second (`per_second`) or per clip (`per_video`) by tier, the tier is named by the controls in `tier_controls`, and nothing shorter than `min_seconds` is billed.

| Field | Meaning |
| --- | --- |
| `model`, `prompt` | required |
| `seconds` or `duration` | the clip's length in seconds, from the model's list |
| `resolution`, `quality`, `aspect_ratio` | the model's own controls, listed under `controls` in `GET /v1/models` |
| `generate_audio` | `true` or `false` on a model with sound |
| `frame_images` | key frames: `[{"image_url": {"url": "data:image/png;base64,…"}, "frame_type": "first_frame"}]`, the second with `last_frame`; `max_frame_images` says how many the model takes |
| `input_reference` | the opening frame as a multipart file (as the OpenAI SDK sends it) or a `data:` string in JSON |

A clip is held at its price before it renders: the price is known in advance from the length and the tier. It is charged once the clip is ready, and `usage.cost` appears then; a clip that did not render costs nothing. The finished file is served until the video object's `expires_at`, after which `GET /v1/videos/{id}/content` answers `410 video_expired`. The clip is not stored here: the file is passed on from the vendor's storage, which deletes it by the same time. The prompt and the frames are not stored either. A remote picture URL is refused (send a `data:` URL or the file); `size`, `input_references` (reference-to-video), `seed`, `callback_url` and `n` above 1 are refused with `400`. Lip-sync and character clips are not sold through this API.

## Audio transcriptions

`POST /v1/audio/transcriptions` turns a recording into text, in OpenAI's audio transcriptions form: the OpenAI SDK's `client.audio.transcriptions.create(...)` works with only the base URL changed. The speech models are in `GET /v1/models` with `architecture.input_modalities: ["audio"]` and `output_modalities: ["transcription"]`; their `pricing.transcription.per_minute` is in roubles per minute of audio, and `max_file_bytes` is the largest file the model takes; cut a longer recording yourself. A minute costs what the vendor bills for it, plus our 20%.

The request is a multipart form. The vendor reads the recording's format from the file name's extension (`meeting.mp3`, `call.ogg`), so the name must carry one. If the speech model is down, during the outage the recording is heard by the substitute model the catalogue names; the answer's `model` field names the one that heard it, and the charge is at its price. An empty or unsure answer does not switch to the substitute. The call takes one request of the key's minute and spends none of the minute's tokens.

```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="en"
```

```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="en",
    )
print(transcript.text)
```

| Field | Meaning |
| --- | --- |
| `file`, `model` | required; the request is a multipart form, the file no larger than the model's `max_file_bytes` |
| `language` | the recording's language as an ISO-639-1 code (`en`, `ru`); without it the model detects the language |
| `prompt` | a hint: names, terms, the style of the previous passage |
| `response_format` | `json` (the default), `text` or `verbose_json` |
| `timestamp_granularities[]` | `word` and `segment`, only with `verbose_json` |

The `json` answer is `{"id", "model", "text", "usage": {"type": "duration", "seconds", "cost", "cost_currency": "RUB"}}`. `verbose_json` adds `task`, `language`, `duration`, `segments: [{"id", "start", "end", "text"}]` and, when `word` was asked for, `words: [{"word", "start", "end"}]`. `text` returns the bare text.

Before the transcription the balance holds an upper estimate from the file size: the lowest sensible bitrate (6 kbit/s) gives the longest recording the file can hold, priced at the dearest model the call can go to, its outage substitute included. After the answer the seconds heard are charged at the per-minute price of the model that answered, and the rest of the hold is released. Neither the recording nor the text is stored. `stream: true`, `temperature`, `chunking_strategy`, `include[]`, `known_speaker_names[]` and `known_speaker_references[]`, and the `srt`, `vtt` and `diarized_json` formats are refused with `400`, not ignored.

## Embeddings

`POST /v1/embeddings` turns text into vectors, in OpenAI's embeddings form: the OpenAI SDK's `client.embeddings.create(...)` works with only the base URL changed. The embedding models are in `GET /v1/models` with `architecture.output_modalities: ["embeddings"]` and on their own list at `GET /v1/embeddings/models` (no key, OpenRouter's model objects). Each has `context_length`, `dimensions` (the model's vector length) and, for a model that can be shortened, `min_dimensions`; `pricing` is `{"currency": "RUB", "unit_tokens": 1000000, "prompt", "completion": "0"}`, roubles per million input tokens. A token costs what the vendor bills for it, plus our 20%; `/v1/models` states today's price.

```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": ["How long does delivery take?", "Delivery within Moscow takes two days."],
    "dimensions": 1024
  }'
```

| Field | Meaning |
| --- | --- |
| `model`, `input` | required; `input` is a string or an array of up to 2048 non-empty strings |
| `encoding_format` | `float` (default) or `base64`: little-endian float32, as at OpenAI |
| `dimensions` | the vector length; only for models with `min_dimensions`, from `min_dimensions` to `dimensions` |
| `user` | your end-user identifier |

The answer: `{"object": "list", "id", "model", "data": [{"object": "embedding", "index", "embedding"}], "usage": {"prompt_tokens", "total_tokens", "cost", "cost_currency": "RUB"}}`. The vectors are unit length: the dot product of two vectors is their cosine similarity. Models such as E5 and Qwen3-Embedding expect their own prefix or instruction on a query; write it into the text itself.

Before the call the balance holds an upper estimate: a token per byte of input and a margin for each string's special tokens. After the answer the tokens the vendor counted are charged and the rest of the hold is released. Neither the text nor the vectors are stored. Input as arrays of token ids, an empty string, `input_type` and a `dimensions` the model cannot give are refused with `400`, not ignored.

## Rerank

`POST /v1/rerank` orders documents by relevance to a query, in the rerank form of OpenRouter, Jina and Cohere v2. The OpenAI SDK has no call for it: send the request yourself or through a Cohere or Jina client with this base URL. The models are in `GET /v1/models` with `architecture.output_modalities: ["rerank"]`, and their `pricing` is the embeddings' one: roubles per million input tokens, already including our 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": "How do I return an item?",
    "documents": [
      "Returns are accepted within two weeks with a receipt.",
      "Delivery within Moscow takes two days.",
      {"text": "Refunds go back to the card you paid with."}
    ],
    "top_n": 2
  }'
```

| Field | Meaning |
| --- | --- |
| `model`, `query`, `documents` | required; a document is a string or `{"text": "…"}`, at most 1000 documents |
| `top_n` | how many of the best to return; without it all are returned |
| `return_documents` | `true` (default) puts the document's text in the answer |
| `instruction` | the task line for a Qwen3 model (by default the model assumes a web search) |
| `user` | your end-user identifier |

The answer: `{"id", "model", "provider", "results": [{"index", "relevance_score", "document": {"text"}}], "usage": {"total_tokens", "cost", "cost_currency": "RUB"}}`. `results` are sorted by `relevance_score`, highest first; `index` is the document's position in the request.

Before the call the balance holds an upper estimate: a token per byte of the query, the instruction and the document of each pair, plus a margin for the model's own prompt. After the answer the tokens the vendor counted are charged and the rest is released. Neither the query nor the documents are stored. Documents with images, `max_tokens_per_doc`, `rank_fields` and `max_chunks_per_doc` are refused with `400`.

## Text to speech

`POST /v1/audio/speech` reads text aloud, in OpenAI's audio speech form: the OpenAI SDK's `client.audio.speech.create(...)` works with only the base URL changed. The models are in `GET /v1/models` with `architecture.output_modalities: ["speech"]`; each has `supported_voices` (the model's voices, the first is the default), `max_input_characters` and `pricing`: `{"currency": "RUB", "unit_characters": 1000000, "input_characters"}`, roubles per million characters of text, already including our 20%. `qwen/qwen3-tts` speaks ten languages, Russian among them.

```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": "Your order is packed and on its way.",
    "voice": "Serena",
    "instructions": "Calm and friendly"
  }' \
  --output speech.mp3
```

| Field | Meaning |
| --- | --- |
| `model`, `input` | required; `input` no longer than the model's `max_input_characters` (4096 characters) |
| `voice` | one of the model's `supported_voices`; the first without it |
| `instructions` | tone and manner of speech, pace included |
| `response_format` | `mp3` (default), `opus`, `flac`, `wav` or `pcm` |
| `user` | your end-user identifier |

The answer is the audio itself, `Content-Type` by its format. The usage rides in headers: `x-request-id`, `x-usage-characters`, `x-usage-cost` in roubles and `x-usage-cost-currency`; `GET /v1/generation?id=<x-request-id>` answers about the same call.

The price is known before the call: the text's characters are held and the same characters are charged after the answer. Neither the text nor the audio is stored. A `speed` other than 1 (ask for the pace in `instructions`), the `aac` format, `stream_format: "sse"`, a custom voice object and a voice the model does not have (`alloy` and OpenAI's other voices) are refused with `400`.

Embeddings, rerank and speech are charged in whole kopecks rounded up, as every balance charge is: a short call costs a kopeck even when the vendor's list price makes it cheaper. If the vendor refuses, the hold is released in full. The same holds when the answer cannot be read (no token count, vectors or audio): the call is refused with `upstream_reply_unreadable` and costs nothing.
