Provider options (advanced knobs)

Provider options (advanced knobs)

Every generation endpoint accepts an optional providerOptions object that is forwarded verbatim to the underlying model. It is how you reach a provider's full capability — resolution, negative prompts, voice emotion, output format, and more — beyond the common fields (prompt, aspectRatio, durationSec).

Rules of the road:

• Optional. Omit providerOptions entirely and you get sensible defaults.
• Per-provider. Each model reads only the fields it understands. Fields a
• model doesn't support are ignored (or rejected by that provider with a clear
• error) — they never silently corrupt a request.
• Forwarded on three endpoints: POST /api/v1/images,
• POST /api/v1/video/generate, and POST /api/v1/tts (voice also takes
• top-level format and speed). POST /api/v1/music uses its own fields
• (tags, instrumental, lyrics, title) instead.

All field names below are confirmed against each provider's live API.

---

Images — POST /api/v1/images

{
  "prompt": "a glossy red paperclip on white, studio light",
  "modelId": "flux-1.1-pro",
  "aspectRatio": "1:1",
  "providerOptions": { "outputFormat": "jpg", "outputQuality": 80 }
}

OpenAI — gpt-image-2 (the old id dall-e-3 is served by it)

fal — flux-1-schnell, ideogram-v3, recraft-v3

Replicate — flux-1.1-pro

Note: flux-1.1-pro has no steps/guidance fields (those belong to flux-dev).

Google — gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image

The Gemini (Nano Banana) image models expose no provider options today — the aspect ratio is passed natively via imageConfig. No seed or negativePrompt.

Imagen 4 is retired: Google shut down imagen-4 / imagen-4-fast on 2026-08-17. Requests for those ids are transparently aliased — imagen-4 → gemini-3-pro-image, imagen-4-fast → gemini-3.1-flash-lite-image — and billed at the successor's price, so the old Imagen personGeneration option is ignored.

WaveSpeed (Varosity Credits) — gpt-image-2.5-flare, gpt-image-2.5-sunburst

Always rendered at 1K (1024 px on the long side); resolution can't be changed. On an edit the output follows the reference image's shape. quality is a REST option: MCP generate_image always uses medium.

---

Video — POST /api/v1/video/generate

{
  "prompt": "a red paper airplane glides over a city, smooth aerial motion",
  "modelId": "seedance-1.0-pro",
  "aspectRatio": "16:9",
  "durationSec": 5,
  "providerOptions": { "resolution": "1080p", "cameraFixed": true }
}

fal — kling-3.0, seedance-1.0-pro, seedance-2.0, seedance-2.0-fast

On Varosity Credits the price covers one tier, so that is what renders: Kling always with audio, Seedance 1.0 Pro at 1080p, Seedance 2.x at 720p, Grok Imagine Video and Wan Animate at 720p. generateAudio: false on Kling, and lower resolutions, take effect only on your own provider key. Seedance 2.x is the exception for audio: generateAudio: false is honoured on Varosity Credits too, at the same per-second price.

Seedance 2.x end frame. Seedance 2.x uses a second reference image as the clip's last frame (a start → end transition). Only the studio sends more than one reference image (a chained start frame plus asset images). POST /api/v1/video/generate and the MCP generate_video tool each take a single reference image, so they can't set an end frame today.

HeyGen — heygen-avatar-4, heygen-photo-avatar, heygen-cinematic

On your own HeyGen key, a missing avatar or voice falls back to a default look and voice from your account. On Varosity Credits there is no default: pass avatarId (or avatarIds for cinematic), and for heygen-avatar-4 and heygen-photo-avatar also voiceId or audioUrl, or the call fails. GET /api/v1/heygen/library lists exactly the public looks and voices Credits renders accept (scope generate:video, free). heygen-photo-avatar takes your photo as the reference image instead of a look.

WaveSpeed (Varosity Credits) — veo-3.1, veo-3.1-quality, veo-3.1-lite, ws-pika-2.2, ws-luma-ray-2, ws-hailuo-02, ws-runway-gen4

Passing a referenceImageUrl on pika/luma/hailuo also triggers image-to-video automatically.

muapi (Varosity Credits) — muapi-wan-t2v, muapi-wan-effects

Replicate — kling-3.0-replicate

Hailuo direct — hailuo-02 (currently unavailable — use ws-hailuo-02, whose options are in the WaveSpeed section above)

---

Voice / TTS — POST /api/v1/tts

Voice takes two top-level fields plus providerOptions:

{
  "text": "Hello from Varosity.",
  "voiceModel": "cartesia-sonic-3.6",
  "format": "wav",                // mp3 | wav | ogg | opus | aac | flac | pcm
  "speed": 1.1,                    // OpenAI 0.25–4.0, Cartesia 0.6–1.5; others (incl. ElevenLabs) ignore
  "providerOptions": { "language": "en", "emotion": "calm" }
}

OpenAI — openai-tts-1, openai-tts-1-hd

Uses the top-level speed (0.25–4.0) and format (mp3/opus/aac/flac/wav/pcm). No extra providerOptions.

Cartesia — cartesia-sonic-3.6, cartesia-sonic-3

Speed, volume and emotion are sent as Cartesia's generation_config. | Field | Type / values | |---|---| | language | "en", "es", "fr", … (Sonic 3.x is multilingual) | | speed | number 0.6–1.5 (1 = normal), or the older words "slowest"…"fastest" | | volume | number 0.5–2.0 (1 = normal) | | emotion | one word, English only, e.g. "calm", "excited", "sad"; older tag arrays like ["positivity:high"] still pass through | | container | "mp3" | "wav" | "raw" | | sampleRate | number (default 44100) | | bitRate | number (mp3, default 128000) | | encoding | "pcm_s16le", "pcm_f32le", … (wav/raw) |

Fish Audio — fish-audio-tts

Deepgram — deepgram-aura-2

Tip: passing top-level "format": "wav" is enough — Deepgram maps it to linear16 in a WAV container for you.

ElevenLabs — elevenlabs-tts, elevenlabs-tts-v3

Pick the model with voiceModel (elevenlabs-tts, elevenlabs-tts-v3) or an ElevenLabs id in modelId (eleven_multilingual_v2, eleven_v3, eleven_flash_v2_5, eleven_turbo_v2_5 — Flash and Turbo cost half), and the voice with voiceId. Output is MP3 (44.1 kHz, 128 kbps). speed, format, stability, similarity and style aren't applied; the voice's own settings are.

---

Music — POST /api/v1/music

Music does not use providerOptions. Use the dedicated fields: tags (genre/mood), instrumental (boolean), lyrics (custom-lyrics mode), and title.