{"openapi":"3.0.3","info":{"title":"MLMux API","version":"2026-10-26","description":"Unified image and video generation API. Credits are US dollars: 1 credit = $1."},"servers":[{"url":"https://api.mlmux.com"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/models":{"get":{"operationId":"listModels","responses":{"200":{"description":"Model IDs available to the account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/v1/images/generations":{"post":{"operationId":"createImageGeneration","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerationRequest"}}}},"responses":{"200":{"description":"Synchronous result (default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"202":{"description":"Queued task when async is true, or the original task on idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageTask"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/images/generations/{task_id}":{"get":{"operationId":"getImageGeneration","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Image task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageTask"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/images/edits":{"post":{"operationId":"createImageEdit","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImageEditRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageEditJSONRequest"}}}},"responses":{"200":{"description":"Synchronous image edit result (default)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"202":{"description":"Queued image edit task when async is true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageTask"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/images/edits/{task_id}":{"get":{"operationId":"getImageEdit","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Image edit task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageTask"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/videos/generations":{"post":{"operationId":"createVideoGeneration","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoGenerationRequest"}}}},"responses":{"202":{"description":"Queued task or original task on idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoTask"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/videos/generations/{task_id}":{"get":{"operationId":"getVideoGeneration","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Video task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoTask"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/tasks/{task_id}":{"get":{"operationId":"getTask","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Task status in the shape of its image, video, or generic task"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/tasks/{task_id}/cancel":{"post":{"operationId":"cancelTask","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Task canceled and held credits released","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["canceled"]}}}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/v1/uploads":{"post":{"operationId":"uploadFile","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Image, video, or audio file up to 50 MB. Kept for 3 days."}}}}}},"responses":{"200":{"description":"Uploaded file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}}},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"}}}},"/v1/account/balance":{"get":{"operationId":"getBalance","responses":{"200":{"description":"Credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An MLMux API key (sk-...)."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Async JSON generation only. Reuse the same key and request body for the same account to retrieve the original task; different content returns 409. Maximum 160 characters. Synchronous requests and image edits do not support this header.","schema":{"type":"string","maxLength":160}}},"schemas":{"RouteMode":{"type":"string","enum":["official","official-cheap"],"description":"Upstream tier. Defaults to the API key's route modes, then the model default (official-cheap)."},"ImageGenerationRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string"},"prompt":{"type":"string","maxLength":20000},"route_mode":{"$ref":"#/components/schemas/RouteMode"},"resolution":{"type":"string","enum":["512","1K","2K","4K"],"description":"Gemini image resolution; Nano Banana and Nano Banana 2 Lite do not use this field."},"size":{"type":"string","description":"GPT Image and Seedream size, such as 1024x1024, 2K, or auto."},"aspect_ratio":{"type":"string","description":"W:H, auto, or match_input_image; allowed values depend on the model."},"output_format":{"type":"string","enum":["jpg","jpeg","png","webp"]},"n":{"type":"integer","minimum":1,"maximum":4,"default":1},"async":{"type":"boolean","default":false,"description":"true returns a task (HTTP 202) instead of the images."}}},"VideoGenerationRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string"},"prompt":{"type":"string"},"mode":{"type":"string","enum":["text_to_video","image_to_video","first_last_frame","multi_ref"],"default":"text_to_video"},"duration":{"type":"integer","minimum":-1,"maximum":30,"description":"Seconds within the model's range (4-15, or 4-30 on Seedance 2.5). Optional on -max models (default 5); -1 lets the model choose."},"ratio":{"type":"string","enum":["adaptive","16:9","9:16","4:3","3:4","1:1","21:9"],"description":"Optional on -max models (default adaptive)."},"resolution":{"type":"string","enum":["480p","720p","1080p","4K"],"description":"Model-specific output resolution. Optional on -max models (default 720p)."},"image_url":{"type":"string","format":"uri","description":"Start frame for image_to_video."},"first_frame_url":{"type":"string","format":"uri"},"last_frame_url":{"type":"string","format":"uri"},"image_urls":{"type":"array","items":{"type":"string","format":"uri"}},"video_urls":{"type":"array","items":{"type":"string","format":"uri"}},"audio_urls":{"type":"array","items":{"type":"string","format":"uri"}},"generate_audio":{"type":"boolean"},"route_mode":{"$ref":"#/components/schemas/RouteMode"}}},"ImageEditRequest":{"type":"object","required":["model","prompt","image"],"properties":{"model":{"type":"string"},"prompt":{"type":"string"},"image":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","format":"binary"},"description":"One or more image files; each file is at most 50 MB."},"mask":{"type":"string","format":"binary"},"route_mode":{"$ref":"#/components/schemas/RouteMode"},"resolution":{"type":"string","enum":["512","1K","2K","4K"]},"size":{"type":"string"},"aspect_ratio":{"type":"string"},"output_format":{"type":"string","enum":["jpg","jpeg","png","webp"]},"n":{"type":"integer","minimum":1,"maximum":4,"default":1},"async":{"type":"boolean","default":false}}},"ImageEditJSONRequest":{"type":"object","required":["model","prompt","image_urls"],"properties":{"model":{"type":"string"},"prompt":{"type":"string"},"image_urls":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"string","format":"uri"},"description":"Public http(s) image URLs; each remote input is limited to 50 MB."},"mask_url":{"type":"string","format":"uri"},"route_mode":{"$ref":"#/components/schemas/RouteMode"},"resolution":{"type":"string","enum":["512","1K","2K","4K"]},"size":{"type":"string"},"aspect_ratio":{"type":"string"},"output_format":{"type":"string","enum":["jpg","jpeg","png","webp"]},"n":{"type":"integer","minimum":1,"maximum":4,"default":1},"async":{"type":"boolean","default":false}}},"ModelList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["model"]},"owned_by":{"type":"string"}}}}}},"ImageResult":{"type":"object","properties":{"created":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"}}}},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}},"TaskStatus":{"type":"string","enum":["queued","submitted","running","succeeded","failed","expired","canceled"]},"ImageTask":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["image.generation.task","image.edit.task"]},"status":{"$ref":"#/components/schemas/TaskStatus"},"created":{"type":"integer"},"model":{"type":"string"},"poll_url":{"type":"string"},"progress":{"type":"integer"},"message":{"type":"string"},"estimated_charge_credits":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"}}},"description":"Present when status is succeeded."}}},"VideoTask":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["video.generation.task"]},"status":{"$ref":"#/components/schemas/TaskStatus"},"created":{"type":"integer"},"model":{"type":"string"},"poll_url":{"type":"string"},"progress":{"type":"integer"},"message":{"type":"string"},"estimated_charge_credits":{"type":"number"},"video":{"type":"string","description":"Present when status is succeeded."},"first_frame_image":{"type":"string"},"last_frame_image":{"type":"string"},"usage":{"type":"object","properties":{"output_tokens":{"type":"integer"},"video_seconds":{"type":"number"},"video_resolution":{"type":"string"}}},"actual_charge_credits":{"type":"number"}}},"Upload":{"type":"object","properties":{"url":{"type":"string"},"asset_id":{"type":"integer"},"mime_type":{"type":"string"},"size_bytes":{"type":"integer"},"asset_type":{"type":"string","enum":["image","video","audio"]}}},"Balance":{"type":"object","properties":{"object":{"type":"string","enum":["credit_balance"]},"available":{"type":"number"},"available_usd":{"type":"number"},"available_nano_credits":{"type":"integer"},"frozen_nano_credits":{"type":"integer"},"total_nano_credits":{"type":"integer"},"usd_per_credit":{"type":"number"},"status":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string"}}}}}},"responses":{"Error":{"description":"MLMux error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}