API Reference

Documentation

OpenAI-compatible REST API across eight modalities. Point your SDK or HTTP client at the base URL below and authenticate with a dashboard API key.

Base URLhttps://multimodal-orchestrator.vercel.app/api/v1

All routes live under /api/v1. Responses follow OpenAI-style JSON with billing headers on every successful call.

Quickstart Browse endpoints Open playground

Getting started

You need an account, credits, and an API key before calling the gateway. Most developers finish this flow in under five minutes.

Step 1
Create an account
Sign up for free — new accounts receive starter credits so you can try models without adding a card.
Step 2
Generate an API key
Open Dashboard → API Keys and create a key. Copy it immediately; the full secret is shown only once.
Step 3
Store the key securely
Set MMG_API_KEY (or your preferred name) in your server environment or secrets manager. Never commit keys to git or ship them in client-side code.
Step 4
Make your first request
Send a POST to /chat/completions with your key in the Authorization header. Check X-Credits-Remaining to confirm billing worked.

New here? Create a free account or open the playground to test models interactively.

Quickstart

Replace $MMG_API_KEY with your secret key, then send a chat completion. Pick a model and language tab below.

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"Explain quantum entanglement simply."}]}'

Successful response

Look for choices[0].message.content in the JSON body, plus X-Credits-Charged and X-Credits-Remaining in response headers.

Authentication

Every request must send your API key as a Bearer token. Keys are prefixed with mmg_live_ and stored as one-way hashes — revoke and recreate if lost.

HeaderAuthorization: Bearer mmg_live_your_key_here

Security guidance

Never embed keys in frontend bundles, mobile apps, or public repos.
Route client traffic through your own backend that holds the key.
Rotate keys periodically and revoke unused keys from the dashboard.
Use separate keys per environment (development, staging, production).

OpenAI SDK compatibility

Reuse official OpenAI client libraries by changing only baseURL and apiKey. Chat, embeddings, and audio routes work out of the box.

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MMG_API_KEY,
  baseURL: "https://multimodal-orchestrator.vercel.app/api/v1",
});

const completion = await client.chat.completions.create({
  model: "llama-3.1-8b",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(completion.choices[0].message.content);

Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["MMG_API_KEY"],
    base_url="https://multimodal-orchestrator.vercel.app/api/v1",
)

completion = client.chat.completions.create(
    model="llama-3.1-8b",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(completion.choices[0].message.content)

List models

GET/api/v1/models

Query available models at runtime. Each entry includes modality, provider, pricing, and context window.

bash

curl https://multimodal-orchestrator.vercel.app/api/v1/models \
  -H "Authorization: Bearer $MMG_API_KEY"

The response is an OpenAI-style list object. Use id as the model field in downstream requests.

Credits & limits

Synapse uses prepaid credits. Each request deducts based on the model's billing unit — tokens, seconds, characters, images, or per-request.

X-Credits-Charged

Credits consumed by this request

X-Credits-Remaining

Your balance after the deduction

RateLimit-Limit / Remaining / Reset

Per-key rate limit window (60 requests per minute)

Inspect pricing on the models page or via GET /models. Low balance returns HTTP 402 with insufficient_credits.

Errors

Failed requests return JSON with an OpenAI-style error object containing type (machine-readable) and message (human-readable).

json

{
  "error": {
    "type": "insufficient_credits",
    "message": "Not enough credits to complete this request."
  }
}

Code	HTTP	Meaning
unauthorized	401	Missing, malformed, or revoked API key.
invalid_request	400	Body failed validation — check required fields and value limits.
model_not_found	404	The model slug does not exist or is disabled.
modality_mismatch	400	The model does not support this endpoint (e.g. TTS model on /chat/completions).
insufficient_credits	402	Your balance is too low. Top up credits from the dashboard.
rate_limited	429	More than 60 requests per minute on this key. Back off and retry.
provider_error	502	Upstream provider failed. Retry with exponential backoff.
provider_not_configured	503	The model's provider is not configured on this deployment.

Best practices

Production tips for secure, reliable integrations.

Call the gateway from your backend or a trusted worker — never from a browser or mobile app where the key can be extracted.
Use GET /models to discover enabled models, pricing units, and context windows at runtime instead of hard-coding slugs.
Handle 402 and 429 explicitly: prompt users to add credits or retry after a delay.
For vision and image-edit endpoints, prefer HTTPS URLs for large images; use base64 only when the image is not publicly reachable.
Log X-Credits-Charged alongside your own request IDs to reconcile usage with your dashboard.
Reuse the OpenAI SDK by setting baseURL to your gateway URL — most chat, embeddings, and audio routes work without code changes.

API reference

Each endpoint accepts POST requests unless noted. Select a model to copy its slug or update the code examples.

Text Generation

POST/api/v1/chat/completions

Chat and completion with open-source LLMs. OpenAI-compatible.

Request body

Field	Type	Required	Description
model	string	No	Model slug (e.g. llama-3.1-8b). Defaults to the gateway default if omitted.
messages	array	Yes	Chat turns with role (system \| user \| assistant) and string or multimodal content.
temperature	number	No	Sampling randomness from 0 to 2. Lower values are more deterministic.
max_tokens	integer	No	Cap on generated tokens (max 32,000).
stream	boolean	No	When true, returns a server-sent events stream (OpenAI-compatible).

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"Hello!"}]}'

Image to Text

POST/api/v1/images/captions

Vision understanding, captioning, and OCR from images.

Image payloads

Pass a public HTTPS URL or inline data:image/...;base64,.... Keep payloads under ~15 MB.

Request body

Field	Type	Required	Description
model	string	No	Vision-capable model slug.
image	string	Yes	Public HTTPS URL or data:image/...;base64,... payload (max ~15 MB).
prompt	string	No	Question or instruction about the image (max 2,000 chars).
max_tokens	integer	No	Maximum length of the caption response.

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/images/captions \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash-vision","image":"data:image/png;base64,<BASE64_IMAGE>","prompt":"What is in this image?"}'

Text to Image

POST/api/v1/images/generations

Generate images from prompts with FLUX and SDXL.

Request body

Field	Type	Required	Description
model	string	No	Image generation model slug (FLUX, SDXL, etc.).
prompt	string	Yes	Text description of the image to generate.
n	integer	No	Number of images to generate (1–4).
width / height	integer	No	Output dimensions between 256 and 1536 pixels.
negative_prompt	string	No	Concepts to avoid in the generated image.

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/images/generations \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-schnell","prompt":"A serene mountain lake at sunrise"}'

Image to Image

POST/api/v1/images/edits

Edit and transform images with a guiding prompt.

Image payloads

Pass a public HTTPS URL or inline data:image/...;base64,.... Keep payloads under ~15 MB.

Request body

Field	Type	Required	Description
model	string	No	Image edit model slug.
image	string	Yes	Source image as a data URI or raw base64 string.
prompt	string	Yes	How to transform the source image.

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/images/edits \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-kontext","image":"data:image/png;base64,<BASE64_IMAGE>","prompt":"Make it look like a watercolor painting"}'

Text to Video

POST/api/v1/videos/generations

Create short video clips from text prompts.

Request body

Field	Type	Required	Description
model	string	No	Video generation model slug.
prompt	string	Yes	Scene description for the clip (max 2,000 chars).

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/videos/generations \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ltx-video","prompt":"A timelapse of clouds over a city"}'

Text to Speech

POST/api/v1/audio/speech

Natural-sounding speech synthesis from text.

Request body

Field	Type	Required	Description
model	string	No	TTS model slug.
input	string	Yes	Text to speak aloud (max 4,000 chars).
voice	string	No	Voice identifier when supported by the model.

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/audio/speech \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"playai-tts","input":"Hello from the gateway!"}'

Speech to Text

POST/api/v1/audio/transcriptions

Fast, multilingual transcription with Whisper.

Multipart upload

Send multipart/form-data with a file field for audio and model for the slug — not JSON.

Request body

Field	Type	Required	Description
file	file	Yes	Audio file (multipart/form-data). Common formats: mp3, wav, m4a.
model	string	Yes	Whisper or transcription model slug.

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -F "file=@/path/to/audio.mp3" \
  -F "model=whisper-large-v3-turbo"

Embeddings

POST/api/v1/embeddings

Vector embeddings for search and RAG (entity-to-entity).

Request body

Field	Type	Required	Description
model	string	No	Embedding model slug.
input	string \| string[]	Yes	One text or a batch of texts to embed.

Code examples

Models — click to use in example, to copy

cURL

curl https://multimodal-orchestrator.vercel.app/api/v1/embeddings \
  -H "Authorization: Bearer $MMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"bge-base-en","input":"The quick brown fox"}'