API Reference

Every public route on api.magicrouter.ai, with parameters, examples, and response shapes. Schema follows the router's apps/router/app/v1/* handlers; bump this page when those change.

Authentication

All endpoints except /v1/models/live and /v1/pricing require an mr-… API key in the Authorization header: `Authorization: Bearer mr-your-key`. Generate and manage keys in the dashboard.

Chat Completions

POST/v1/chat/completionsAPI key (Bearer mr-…)

Create chat completion

OpenAI-compatible chat completion. Streaming (SSE), tool calling, vision (image_url content blocks), and JSON mode all supported. The full body schema mirrors OpenAI's /v1/chat/completions — see https://platform.openai.com/docs/api-reference/chat/create for every field. The router accepts and forwards unknown fields with extra="allow".

Name	In	Type	Description
model*	body	string	Model slug, e.g. "qwen/qwen3.7-max" or bare "qwen3.6-plus". Append ":<provider>" to pin a provider, e.g. "qwen/qwen3-max:alibaba".
messages*	body	array	Standard OpenAI messages array. `content` may be a string or a list of {type:"text"\|"image_url", …} blocks for vision-capable models.
stream	body	boolean	Stream the response as SSE chunks. Default false.
temperature	body	number	0–2. Default 1.0.
top_p	body	number	Nucleus sampling. Default 1.0.
top_k	body	number	Forwarded to providers that support it (e.g. Alibaba). Ignored otherwise.
max_tokens	body	number	Cap on completion tokens.
stop	body	string \| string[]	Up to 4 stop sequences.
frequency_penalty	body	number	−2.0 to 2.0.
presence_penalty	body	number	−2.0 to 2.0.
repetition_penalty	body	number	Alibaba-specific; forwarded when present.
response_format	body	object	{ "type": "json_object" } enables JSON mode where supported.
tools	body	array	OpenAI tool/function-calling schema.
tool_choice	body	string \| object	"auto" \| "none" \| {type:"function", function:{name}}
seed	body	number	Forwarded to providers that honor it.
user	body	string	Opaque end-user id for abuse tracking.

Example request

curl https://api.magicrouter.ai/chat/completions \
  -H "Authorization: Bearer mr-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.7-max",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

Example response

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1747400000,
  "model": "qwen/qwen3.7-max",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello! How can I help?"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17}
}

Image Generation

POST/v1/images/generationsAPI key (Bearer mr-…)

Create image

Text-to-image and image-edit on a single endpoint. Pure text-to-image models ignore `image`/`images`; edit models (qwen-image-edit-plus / qwen-image-edit-max) require at least one reference image.

Name	In	Type	Description
model*	body	string	e.g. "qwen/qwen-image-2.0-pro", "qwen/qwen-image-edit-plus".
prompt*	body	string	Description of the image to generate.
n	body	integer	How many images to generate. Default 1.
size	body	string	Output dimensions, e.g. "1024x1024" or "1280*720".
quality	body	string	"standard" \| "hd" — model-specific.
response_format	body	string	"url" (default) \| "b64_json".
image	body	string	Single reference image (HTTPS URL or data: URI) for image-to-image/edit models.
images	body	string[]	1–3 reference images for multi-reference edit models. Takes precedence over `image`.

Example request

curl https://api.magicrouter.ai/images/generations \
  -H "Authorization: Bearer mr-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen-image-2.0-pro",
    "prompt": "A watercolor mountain village at dawn",
    "size": "1024x1024",
    "n": 1
  }'

Example response

{
  "created": 1747400000,
  "data": [
    { "url": "https://dashscope-result-…/output.png" }
  ]
}

Video Generation (Async)

Video generation is asynchronous: POST returns a task id immediately; GET the task id until status is "succeeded" (then video_url is populated) or "failed". Worst case ~10 min for 1080P / 15s.

POST/v1/videos/generationsAPI key (Bearer mr-…)

Submit video generation

Submit a t2v / i2v / r2v / videoedit job. Returns a task id immediately. Poll with GET /v1/videos/generations/{id}.

Name	In	Type	Description
model*	body	string	happyhorse-1.0-t2v, happyhorse-1.0-i2v, wan2.7-t2v, wan2.7-i2v, wan2.7-r2v, wan2.7-videoedit.
prompt*	body	string	Text description.
image	body	string	i2v first frame (HTTPS URL or data: URI). Required for i2v models.
last_image	body	string	Optional last frame for wan2.7-i2v interpolation. Ignored by HappyHorse i2v.
ref_images	body	string[]	Reference images. Required for wan2.7-r2v (up to 5) and the reference slot of wan2.7-videoedit (up to 3).
input_video	body	string	Source video for wan2.7-videoedit. Must be a public HTTP(S) URL — data: URI is not accepted.
duration	body	integer	Seconds. Model-specific bounds (typically 3–15).
resolution	body	string	"480P" \| "720P" \| "1080P". Cheapest tier the model supports wins on pricing.
ratio	body	string	"16:9" \| "9:16" \| "1:1". t2v only — i2v / r2v / videoedit derive aspect from refs.
negative_prompt	body	string	What to avoid.
prompt_extend	body	boolean	Provider-side prompt rewriting.
watermark	body	boolean	Provider watermark toggle.
seed	body	integer	Reproducibility seed (forwarded where supported).

Example request

curl https://api.magicrouter.ai/videos/generations \
  -H "Authorization: Bearer mr-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "A panda surfing a tropical wave, slow-motion 4K",
    "duration": 5,
    "resolution": "720P",
    "ratio": "16:9"
  }'

Example response

{
  "id": "vid-abc123…",
  "status": "processing",
  "video_url": null,
  "created": 1747400000
}

GET/v1/videos/generations/{task_id}API key (Bearer mr-…)

Poll video status

Returns the current status of an in-flight or completed task. video_url is set when status="succeeded". On "failed", error_code and error_message describe the upstream rejection.

Name	In	Type	Description
task_id*	path	string	Task id returned by the submit call.

Example request

curl https://api.magicrouter.ai/videos/generations/vid-abc123 \
  -H "Authorization: Bearer mr-your-key"

Example response

{
  "id": "vid-abc123…",
  "status": "succeeded",
  "video_url": "https://dashscope-result-…/output.mp4",
  "duration_seconds": 5.0,
  "created": 1747400000
}

Audio (Text-to-Speech)

POST/v1/audio/speechAPI key (Bearer mr-…)

Create TTS audio

OpenAI-compatible TTS. Returns the audio bytes directly with the appropriate Content-Type.

Name	In	Type	Description
model*	body	string	TTS model id (Qwen TTS or compatible).
input*	body	string	Text to synthesize.
voice	body	string	Voice id. Default "alloy".
speed	body	number	0.25–4.0. Default 1.0.
response_format	body	string	"mp3" (default) \| "wav" \| "opus".

Example request

curl https://api.magicrouter.ai/audio/speech \
  -H "Authorization: Bearer mr-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-tts",
    "input": "Hello from MagicRouter",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Example response

(binary audio body; Content-Type: audio/mpeg | audio/wav | audio/opus)

Models

GET/v1/modelsAPI key (Bearer mr-…)

List models (registry)

OpenAI-shaped list of every model in the static registry merged with the live DashScope catalog (static wins on collision). Add ?details=1 to include providers + pricing.

Name	In	Type	Description
details	query	boolean	When 1, each entry includes a providers[] array with adapter, input_per_m, output_per_m.

Example request

curl https://api.magicrouter.ai/models?details=1 \
  -H "Authorization: Bearer mr-your-key"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "qwen/qwen3.7-max",
      "object": "model",
      "created": 1747400000,
      "owned_by": "qwen3.7",
      "providers": [
        {"id": "alibaba", "adapter": "alibaba", "input_per_m": 2.5, "output_per_m": 7.5}
      ]
    }
  ]
}

GET/v1/models/livePublic

Live DashScope catalog

Categorized chat / image / video model id lists. Refreshed hourly from DashScope's /compatible-mode/v1/models, with the video models DashScope's compat-mode endpoint doesn't expose patched in. Returns 503 + Retry-After: 10 on a cold cache.

Example request

curl https://api.magicrouter.ai/models/live

Example response

{
  "chat":  ["qwen3.7-max", "qwen3.6-plus", "qwen3-max", …],
  "image": ["qwen-image-2.0-pro", "wan2.7-image", …],
  "video": ["happyhorse-1.0-t2v", "wan2.7-t2v", …],
  "total": 72,
  "synced_at": "2026-05-24T05:00:00Z"
}

Pricing

GET/v1/pricingPublic

Get pricing map

Per-model pricing for all providers, in both `intl` (USD) and `cn` (USD converted from CNY). Chat uses input_per_m + output_per_m (per 1M tokens). Images use output_per_m (per image). Videos use output_per_m (per second, flat) + output_per_m_by_tier (per resolution tier). Cache-Control: public, max-age=300, stale-while-revalidate=600.

Example request

curl https://api.magicrouter.ai/pricing

Example response

{
  "models": {
    "qwen/qwen3.7-max": {
      "id": "qwen/qwen3.7-max",
      "modality": "text",
      "family": "qwen3.7",
      "providers": [{
        "id": "alibaba",
        "adapter": "alibaba",
        "intl": { "input_per_m": 2.5, "output_per_m": 7.5 },
        "cn":   { "input_per_m": 1.7647, "output_per_m": 5.2941 }
      }]
    }
  }
}

Credits & Billing

GET/v1/credits/balanceAPI key (Bearer mr-…)

Get credit balance

Current credit balance for the authenticated user. /v1/billing/balance is an alias of this endpoint.

Example request

curl https://api.magicrouter.ai/credits/balance \
  -H "Authorization: Bearer mr-your-key"

Example response

{ "balance": 12.345, "auto_topup_enabled": false }

GET/v1/billing/balanceAPI key (Bearer mr-…)

Get balance (alias)

Alias of /v1/credits/balance. Identical response shape.

GET/v1/billing/transactionsAPI key (Bearer mr-…)

List recent transactions

Paginated list of the user's credit transactions, newest first.

Name	In	Type	Description
limit	query	integer	1–500. Default 50.
offset	query	integer	≥0. Default 0.

Example request

curl "https://api.magicrouter.ai/billing/transactions?limit=10" \
  -H "Authorization: Bearer mr-your-key"

GET/v1/billing/analyticsAPI key (Bearer mr-…)

Usage analytics

Aggregates the user's usage_events over a rolling window into by-day, by-model, by-source breakdowns. Powers the dashboard's usage graphs.

Name	In	Type	Description
days	query	integer	1–365. Default 30.

Example request

curl "https://api.magicrouter.ai/billing/analytics?days=30" \
  -H "Authorization: Bearer mr-your-key"

Example response

{
  "window_days": 30,
  "by_day":    [{ "day": "2026-05-23", "requests": 412, "tokens_in": 18203, "tokens_out": 6442 }],
  "by_model":  [{ "model": "qwen/qwen3.6-plus", "requests": 200, "cost": 0.0834 }],
  "by_source": [{ "source": "sdk", "requests": 380, "cost": 0.42 }]
}

* required. All endpoints live under https://api.magicrouter.ai. Authenticated endpoints accept the API key as Authorization: Bearer mr-….