Media backends

merido also fronts image generation, text-to-speech (TTS), and speech-to-text (transcription/STT) — separate endpoints from chat completions, but the same gateway key, the same connected providers, and the same dashboard. Any provider you already have an API-key connection for can be turned into a media backend; no separate credential is needed.

How it's different from chat

• Separate endpoints. Media doesn't go through the chat completions / messages / responses surface — it's /v1/images/* and /v1/audio/* (below). There's no cross-format translation the way there is for text (see Virtual models & fallback): a request is shaped for whichever backend the resolved provider maps to and the result relayed back in an OpenAI-compatible envelope.
• Must be explicitly enabled. Unlike chat models — servable the moment a provider is connected — an image/audio backend must be turned on in the dashboard first (see below). This keeps a provider you use for chat from silently becoming an image/speech bill too.
• Not token-billed. Audio requests aren't measured in tokens (there's nothing to count), so usage rows for /v1/audio/* always show zero prompt/completion tokens — you still see the request logged, just without a token cost line.

The enabled gate

Every /v1/images/* and /v1/audio/* request is checked against your org's saved media configuration before it's forwarded upstream:

• No saved config, or saved but disabled → 403 Forbidden. Having a connected provider is not enough by itself — the provider must also be turned on as a media backend.
• Enabled, but no model specified and no default configured → 400 Bad Request. See bare-provider defaults below.

Enable a backend from the dashboard: Models (/app/models) → Media tab. Every provider you have a connection for shows up there — flip it on, optionally set a default model (and a default voice for TTS), and use the tab's Test button to confirm the saved credential actually reaches the provider.

Known media-capable providers, plus anything you've connected

merido ships a static capability hint for providers with a well-known image/TTS/STT API (OpenAI, Gemini, xAI, Groq, Mistral, Together, Fireworks, DeepInfra, Novita, NVIDIA, Hyperbolic, SiliconFlow, …) so the Media tab can show you which modality each one likely supports. But the gate itself doesn't care about that list — any provider you have a connection to can be enabled as a media backend, known or not. If a provider's actual wire format has no OpenAI-compatible image or audio API (e.g. a native Anthropic or native Gemini connection), the request still reaches the gate, but the upstream call itself then fails with 400 since there's no equivalent endpoint to call.

Bare-provider defaults vs. a full model ref

The model field in a media request accepts two shapes:

• Bare provider — e.g. "model": "openai". merido fills in the org's configured default model for that provider (and, for TTS, the default voice if the request doesn't send one). If no default model is configured yet, the request fails with 400 telling you which provider needs one.
• Full provider/model — e.g. "model": "openai/dall-e-3". The explicit model always wins, overriding whatever default is configured — handy for one-off requests against a different model than your default.

Set the default(s) in the Media tab's Configure panel for that backend; they're exactly what a bare-provider request resolves to.

The three endpoint families

All three take the same gateway key you use for chat (Authorization: Bearer <key>) and respect the same rate limits, but they're tracked differently from chat: audio requests (/v1/audio/speech, /v1/audio/transcriptions, /v1/audio/translations) get recorded in Usage as a zero-token row (not token-billed, but still logged as a request against the same key), while image requests (/v1/images/*) aren't recorded in Usage at all. Neither shows up in the Logs view — that covers the chat completions / messages / responses path only.

Image generation — POST /v1/images/generations

curl http://127.0.0.1:8788/v1/images/generations \
  -H "Authorization: Bearer $MERIDO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai","prompt":"a red bicycle"}'

Returns the OpenAI image envelope, { "created": …, "data": [{ "url": … } | { "b64_json": … }] }. The OpenAI-compatible path (the default for most providers) forwards the request as-is; a few providers — Fal, Black Forest Labs (BFL), Stability AI, ComfyUI — speak their own protocol instead, and merido shapes the request and maps the response back to the same envelope, so your client code doesn't need to know which backend actually served it.

POST /v1/images/edits and POST /v1/images/variations cover image editing and variation generation the same way, as OpenAI-compatible multipart uploads (up to 64 MB) — see API endpoints for the full list.

Text-to-speech — POST /v1/audio/speech

curl http://127.0.0.1:8788/v1/audio/speech \
  -H "Authorization: Bearer $MERIDO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai","input":"hello","voice":"alloy"}' --output speech.mp3

The response is the raw audio bytes, streamed straight through with the upstream's Content-Type (e.g. audio/mpeg) — --output (or your client's binary body handling) writes it to a file. Omit voice to use the backend's configured default voice.

Discover the voices a provider offers with GET /v1/audio/voices?provider=openai — each entry's model field is already namespaced (openai/alloy) so you can drop it straight into the model field above to skip the default and pick a specific voice explicitly.

Transcription — POST /v1/audio/transcriptions

curl http://127.0.0.1:8788/v1/audio/transcriptions \
  -H "Authorization: Bearer $MERIDO_KEY" \
  -F model=openai -F [email protected]

A multipart upload (up to 64 MB); the result format depends on the upstream (json, verbose_json, plain text, srt, vtt, …) and is relayed with its original Content-Type. POST /v1/audio/translations is the same shape but always returns an English translation of the spoken audio, regardless of the source language.

Where to go next

• Add providers & keys — connect the provider a media backend needs a credential from.
• API endpoints — the full /v1/images/* / /v1/audio/* table alongside every other endpoint.
• Usage & the Advisor — where image/audio requests show up in spend and logs.