{"openapi":"3.1.0","info":{"title":"Mixen API","description":"OpenAI-compatible API for [Mixen AI](https://mixen.ai). **Drop-in**: point any\nOpenAI client at this base URL and use your Mixen key — nothing else changes.\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"https://api.mixen.ai/v1\", api_key=\"mxn-...\")\nresp = client.chat.completions.create(\n    model=\"gpt-5.5\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n)\n```\n\n* **Auth** — `Authorization: Bearer mxn-...`. Create keys in your\n  [cabinet](https://mixen.ai/account/profile/api).\n* **Billing** — from your Mixen balance.\n* **Rate limit** — 60 requests/min per key by default (`429` + `Retry-After`).\n* **Endpoints** — `chat/completions`, `images/generations`, `audio/speech` (TTS),\n  `audio/transcriptions` (STT), `embeddings`, `models`.\n* **Models** — `GET /models` returns the live catalog with display names, pricing\n  (RUB + USD, identical to what is charged) and capabilities. Pass the `id` (or a\n  common OpenAI/Claude/Gemini name, e.g. `gpt-4o`, `claude-opus`) in the `model` field.\n","version":"1.0"},"paths":{"/models":{"get":{"tags":["models"],"summary":"List models","description":"Live catalog of available models with display names, per-unit pricing (RUB + USD, identical to what is charged) and capabilities. Each entry has a `type` (text/search/image/video/music/tts/stt/embeddings) telling you which endpoint to call. For text models, `capabilities.reasoning_efforts` lists the valid `reasoning_effort` values and `can_disable_reasoning` whether `\"off\"` is accepted; image models expose `references` (image-to-image via /images/edits). Pass an `id` in the `model` field of a request; common OpenAI/Anthropic/Google names (e.g. `gpt-4o`, `claude-opus`) are also accepted.","operationId":"list_models","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Models"}}}}}}},"/chat/completions":{"post":{"tags":["chat"],"summary":"Create chat completion","description":"OpenAI-compatible chat completion. Set `stream=true` for SSE token streaming; otherwise returns a single `chat.completion` object. Charged per-token from balance. Supports vision (image_url data: parts on vision models) and Perplexity Sonar (category=search models) — web results return as message.annotations (url_citation).","operationId":"chat_completions","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/images/generations":{"post":{"tags":["images"],"summary":"Create image","description":"OpenAI-compatible text-to-image. Returns base64 images (`b64_json`); `url` is not supported. Models: see GET /models (image), or `dall-e-3`/`gpt-image-1`. Charged per image.","operationId":"create_image","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/images/edits":{"post":{"tags":["images"],"summary":"Edit image (image-to-image)","description":"OpenAI-compatible image-to-image: multipart `image` (one or more reference images) + `prompt` + `model`. Returns base64 (`b64_json`). Only models that accept image input (GET /models → image with `references: true`): Nano Banana / GPT Image 2 / Seedream / Flux. `aspect_ratio`+`resolution` (or `size`) optional. Charged per image.","operationId":"create_image_edit","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_image_edit"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/audio/speech":{"post":{"tags":["audio"],"summary":"Text to speech","description":"OpenAI-compatible TTS. Returns mp3 audio. Served by gpt-4o-mini-tts; OpenAI voices (alloy, echo, fable, nova, shimmer, ...) are accepted. Charged per input characters.","operationId":"create_speech","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/audio/transcriptions":{"post":{"tags":["audio"],"summary":"Transcribe audio","description":"OpenAI-compatible STT (multipart: file + model). Served by whisper-large-v3-turbo. Returns `{\"text\": ...}` (or plain text if response_format=text). Charged per minute of audio. Max file size 25 MB.","operationId":"create_transcription","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_transcription"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/embeddings":{"post":{"tags":["embeddings"],"summary":"Create embeddings","description":"OpenAI-compatible embeddings. `input` is a string or array of strings. Models: text-embedding-3-small (1536-dim) / -large (3072-dim). Charged per input token.","operationId":"create_embeddings_ep","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/videos":{"post":{"tags":["videos"],"summary":"Create video","description":"OpenAI-compatible async video job. Returns a Video object (status=queued). Poll GET /videos/{id} until status=completed, then GET /videos/{id}/content for the mp4. Models: sora-2 / sora-2-pro, or Mixen ids (kling-v3-pro, veo-3.1, seedance-2.0, happyhorse-1.1).","operationId":"create_video","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/videos/{video_id}":{"get":{"tags":["videos"],"summary":"Retrieve video","description":"Poll the video job. status: queued | in_progress | completed | failed.","operationId":"get_video","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/videos/upscale":{"post":{"tags":["videos"],"summary":"Upscale a video","description":"Video upscaling (FLUX Video Upscale). Multipart: a `video` file (mp4), optional `prompt`, `upscale_factor` (1.5–3.0, default 1.5) and `creativity` (0.0–1.0, default 0.0). Billed per megapixel-second of the output — the exact amount depends on the source, so the charge is settled from the actual upstream cost once the job completes. Returns a Video object; poll GET /videos/{id}.","operationId":"create_video_upscale","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_video_upscale"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/videos/{video_id}/content":{"get":{"tags":["videos"],"summary":"Download video content","description":"Returns the mp4 (Range supported) once status=completed.","operationId":"get_video_content","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string","title":"Video Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/audio/music":{"post":{"tags":["music"],"summary":"Create music","description":"Async music generation (job+poll). Suno (model \"suno\") returns 2 tracks; Lyria (\"lyria\"/\"lyria-pro\") returns 1 instrumental track. Poll GET /audio/music/{id} until status=completed, then GET .../content?index=N for the mp3.","operationId":"create_music","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MusicCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/audio/music/{music_id}":{"get":{"tags":["music"],"summary":"Retrieve music","description":"Poll the music job. status: queued | in_progress | completed | failed.","operationId":"get_music","parameters":[{"name":"music_id","in":"path","required":true,"schema":{"type":"string","title":"Music Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/audio/music/{music_id}/content":{"get":{"tags":["music"],"summary":"Download music content","description":"Returns an mp3 track (Range supported) once status=completed. Use ?index=N to select a track (Suno yields 2, Lyria 1; default 0).","operationId":"get_music_content","parameters":[{"name":"music_id","in":"path","required":true,"schema":{"type":"string","title":"Music Id"}},{"name":"index","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Index"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_create_image_edit":{"properties":{"image":{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array","title":"Image","description":"Reference image(s) for image-to-image."},"model":{"type":"string","title":"Model"},"prompt":{"type":"string","title":"Prompt"},"n":{"type":"integer","title":"N","default":1},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size"},"aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspect Ratio"},"resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution"},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality"},"response_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Format"}},"type":"object","required":["image","model","prompt"],"title":"Body_create_image_edit"},"Body_create_transcription":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"model":{"type":"string","title":"Model","default":"whisper-1"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"response_format":{"type":"string","title":"Response Format","default":"json"}},"type":"object","required":["file"],"title":"Body_create_transcription"},"Body_create_video_upscale":{"properties":{"video":{"type":"string","contentMediaType":"application/octet-stream","title":"Video","description":"Source mp4 to enlarge"},"prompt":{"type":"string","title":"Prompt","default":"Upscale this video, keep every detail sharp"},"upscale_factor":{"type":"number","title":"Upscale Factor","default":1.5},"creativity":{"type":"number","title":"Creativity","default":0.0}},"type":"object","required":["video"],"title":"Body_create_video_upscale"},"ChatCompletionRequest":{"properties":{"model":{"type":"string","title":"Model","description":"Model id from GET /models, or a common OpenAI/Claude/Gemini alias."},"messages":{"items":{"$ref":"#/components/schemas/_Msg"},"type":"array","title":"Messages","description":"Conversation so far; the last user message is the prompt."},"stream":{"type":"boolean","title":"Stream","description":"If true, stream tokens as SSE (text/event-stream).","default":false},"stream_options":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Stream Options","description":"e.g. {\"include_usage\": true} to append a usage chunk."},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature"},"max_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Tokens"},"max_completion_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Completion Tokens"},"reasoning_effort":{"anyOf":[{"type":"string","enum":["off","low","medium","high","xhigh","max"]},{"type":"null"}],"title":"Reasoning Effort"}},"type":"object","required":["model","messages"],"title":"ChatCompletionRequest","example":{"messages":[{"content":"Hello!","role":"user"}],"model":"gpt-5.5","stream":false}},"EmbeddingsRequest":{"properties":{"model":{"type":"string","title":"Model","description":"text-embedding-3-small | text-embedding-3-large (or text-embedding-ada-002)."},"input":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"Input","description":"A string or array of strings to embed."},"encoding_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Encoding Format"}},"type":"object","required":["model","input"],"title":"EmbeddingsRequest","example":{"input":"hello world","model":"text-embedding-3-small"}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImageGenRequest":{"properties":{"model":{"type":"string","title":"Model","description":"Image model id from GET /models, or dall-e-3 / gpt-image-1."},"prompt":{"type":"string","title":"Prompt"},"n":{"type":"integer","maximum":4.0,"minimum":1.0,"title":"N","description":"Number of images (1-4).","default":1},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size","description":"WxH; allowed values are per-model (see GET /models). Alternative to aspect_ratio+resolution."},"aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspect Ratio","description":"E.g. 16:9; allowed values are per-model (see GET /models). Defaults to 1:1."},"resolution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution","description":"1k | 2k | 4k; allowed values are per-model (see GET /models). Defaults to 1k."},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality","description":"low | medium — only on models exposing a quality knob (e.g. grok-imagine-image-2)."},"response_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Format"}},"type":"object","required":["model","prompt"],"title":"ImageGenRequest","example":{"model":"gpt-image-1","prompt":"a red cat","size":"1024x1024"}},"MusicCreateRequest":{"properties":{"model":{"type":"string","title":"Model","description":"suno / suno-v5 (song with vocals, 2 tracks) or lyria / lyria-pro (instrumental, 1 track).","default":"suno"},"prompt":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Prompt","description":"Track description (Suno simple / Lyria). Unused in Suno custom mode."},"mode":{"type":"string","title":"Mode","description":"Suno: simple (from prompt) | custom (from lyrics+style+title). Ignored by Lyria.","default":"simple"},"lyrics":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Lyrics","description":"Suno custom: song lyrics."},"style":{"type":"string","maxLength":500,"title":"Style","description":"Suno custom: genre, style, tags.","default":""},"title":{"type":"string","maxLength":200,"title":"Title","description":"Suno custom: track title.","default":""}},"type":"object","title":"MusicCreateRequest","example":{"model":"suno","prompt":"lo-fi hip-hop, rain outside the window, calm"}},"SpeechRequest":{"properties":{"model":{"type":"string","title":"Model","description":"Accepted for compatibility; served by gpt-4o-mini-tts.","default":"tts-1"},"input":{"type":"string","title":"Input","description":"Text to synthesize."},"voice":{"type":"string","title":"Voice","description":"alloy, echo, fable, nova, shimmer, ... (unknown → default).","default":"alloy"},"response_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Format"},"speed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Speed"}},"type":"object","required":["input"],"title":"SpeechRequest","example":{"input":"Hello there!","model":"tts-1","voice":"alloy"}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VideoCreateRequest":{"properties":{"model":{"type":"string","title":"Model","description":"sora-2 / sora-2-pro, or a Mixen model (kling-v3-pro, veo-3.1, seedance-2.0, happyhorse-1.1).","default":"sora-2"},"prompt":{"type":"string","maxLength":32000,"minLength":1,"title":"Prompt"},"seconds":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seconds","description":"Duration in seconds; allowed values are per-model (see GET /models); defaults to the model minimum."},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size","description":"Size WxH; allowed values are per-model (see GET /models); defaults to the model 16:9 720p."},"input_reference":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Reference","description":"Image-to-video: {\"image_url\": \"data:image/...;base64,...\"} (data: URLs only)."},"input_references":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Input References","description":"Reference-to-video (Seedance 2.0 / Happy Horse 1.1 only): 2-9 images as data: URLs."}},"type":"object","required":["prompt"],"title":"VideoCreateRequest","example":{"model":"sora-2","prompt":"an astronaut cat riding a motorcycle at night","seconds":"4","size":"720x1280"}},"_Msg":{"properties":{"role":{"type":"string","title":"Role"},"content":{"title":"Content"}},"type":"object","required":["role"],"title":"_Msg"}},"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"mxn-..."}}},"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"models","description":"List available models"},{"name":"chat","description":"Chat completions (text, vision). Web search via Perplexity Sonar models."},{"name":"images","description":"Image generation"},{"name":"videos","description":"Video generation (async job + poll)"},{"name":"music","description":"Music generation (async job + poll)"},{"name":"audio","description":"Text-to-speech and transcription"},{"name":"embeddings","description":"Text embeddings"}],"servers":[{"url":"/v1"}]}