{ "openapi": "3.1.0", "info": { "title": "Mage API", "version": "v1", "description": "Run Mage models from your own code: submit a generation, poll its status, download the result. Every request is paid in gems.", "contact": { "name": "Mage", "url": "https://www.mage.space", "email": "mage@mage.space" } }, "servers": [ { "url": "https://api.mage.space", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Requests", "description": "Submit, poll, and cancel generations." }, { "name": "Catalog", "description": "What the API can generate with." }, { "name": "Account", "description": "The gems balance." }, { "name": "Uploads", "description": "Large input files." }, { "name": "Characters", "description": "Saved characters a prompt mentions by `@handle`." }, { "name": "References", "description": "Saved image and audio references a prompt mentions by `@handle`." }, { "name": "Image models", "description": "One endpoint per image architecture." }, { "name": "Video models", "description": "One endpoint per video architecture." }, { "name": "Audio models", "description": "One endpoint per audio architecture." } ], "paths": { "/v1/{architecture}/generate": { "post": { "operationId": "generate", "summary": "Generate", "description": "Submit a generation with any architecture.", "tags": [ "Requests" ], "parameters": [ { "name": "architecture", "in": "path", "required": true, "description": "The architecture id, from the catalog.", "schema": { "type": "string", "enum": [ "mango", "krea_2", "minimax_h3", "z_image", "stable_diffusion_xl", "kiwi", "blueberry", "wan_22", "flux2", "chroma", "hidream", "ltx_video", "stable_diffusion_v15", "stable_diffusion_v35_large", "guava", "nano_banana_v2", "sdxl_plus", "cherry", "raspberry", "grok_image", "grok_video", "berry", "gpt_image_2", "anima", "melon", "seed_audio", "plum", "lemon" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for the architecture.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "flux2", "model_id": "flux2-dev", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 40 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "404": { "description": "No such architecture.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "architecture_not_found", "message": "Unknown architecture `fluxx`. List architectures at GET /v1/architectures." } } } } }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.generate('mango', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.request_id, request.status);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.generate(\"mango\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"request_id\"], request[\"status\"])" } ] } }, "/v1/architectures": { "get": { "operationId": "list_architectures", "summary": "List architectures", "description": "Every architecture the API can generate with, with its fields, tokens, defaults, and price.", "tags": [ "Catalog" ], "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchitectureList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst { architectures } = await mage.architectures.list();\n\nfor (const architecture of architectures) {\n console.log(architecture.id, architecture.gems);\n}" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\ncatalog = mage.architectures.list()\n\nfor architecture in catalog[\"architectures\"]:\n print(architecture[\"id\"], architecture[\"gems\"])" } ] } }, "/v1/requests/{request_id}/status": { "get": { "operationId": "get_request_status", "summary": "Get request status", "description": "The state, result, and billing of a request.", "tags": [ "Requests" ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The `request_id` from the submit response.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The request's current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "examples": { "in_progress": { "summary": "Generating", "value": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "flux2", "model_id": "flux2-dev", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 40 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } }, "completed": { "summary": "Completed", "value": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "completed", "architecture": "flux2", "model_id": "flux2-dev", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:53:10.000Z", "billing": { "mode": "gems", "gems_charged": 40 }, "result": { "type": "image", "url": "https://cdn3.mage.space/temp/30d/user/image.png", "width": 1024, "height": 1280, "seed": 1234567, "expires_at": "2026-10-17T14:52:48.000Z", "moderation": { "nsfw": false } }, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } }, "failed": { "summary": "Failed and refunded", "value": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "failed", "architecture": "flux2", "model_id": "flux2-dev", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:53:02.000Z", "billing": { "mode": "gems", "gems_charged": 40, "gems_refunded": 40 }, "result": null, "error": { "code": "generation_failed", "message": "The generation failed. Any gems charged were refunded." }, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/RequestNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.requests.get('REQUEST_ID');\n\n// Or poll until it is completed, failed, or cancelled:\nconst final = await mage.requests.wait('REQUEST_ID');\nconsole.log(final.status, final.result?.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.requests.get(\"REQUEST_ID\")\n\n# Or poll until it is completed, failed, or cancelled:\nfinal = mage.requests.wait(\"REQUEST_ID\")\nprint(final[\"status\"], final[\"result\"] and final[\"result\"][\"url\"])" } ] } }, "/v1/requests/{request_id}/cancel": { "post": { "operationId": "cancel_request", "summary": "Cancel request", "description": "Stop a live request. Gems are not refunded.", "tags": [ "Requests" ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The `request_id` from the submit response.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The request's state after the cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "cancelled", "architecture": "flux2", "model_id": "flux2-dev", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:55.000Z", "billing": { "mode": "gems", "gems_charged": 40 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/RequestNotFound" }, "409": { "description": "The request already finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "request_finished", "message": "The request has already finished and cannot be cancelled." } } } } }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.requests.cancel('REQUEST_ID');\n\nconsole.log(request.status); // cancelled" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.requests.cancel(\"REQUEST_ID\")\n\nprint(request[\"status\"]) # cancelled" } ] } }, "/v1/account": { "get": { "operationId": "get_account", "summary": "Get account", "description": "The gems balance the API draws from.", "tags": [ "Account" ], "responses": { "200": { "description": "The balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "gems": { "balance": 1250 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst account = await mage.account.get();\n\nconsole.log(account.gems.balance);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\naccount = mage.account.get()\n\nprint(account[\"gems\"][\"balance\"])" } ] } }, "/v1/uploads": { "post": { "operationId": "create_upload", "summary": "Create upload", "description": "A signed URL to upload one input file, for files too large for a data URL.", "tags": [ "Uploads" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" }, "example": { "content_type": "video/mp4" } } } }, "responses": { "200": { "description": "The upload ticket.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadTicket" }, "example": { "upload_url": "https://storage.googleapis.com/mage/temp/30d/uploads/user/video/6f1c.mp4?X-Goog-Signature=…", "method": "PUT", "headers": { "Content-Type": "video/mp4", "x-goog-content-length-range": "0,104857600" }, "url": "https://cdn3.mage.space/temp/30d/uploads/user/video/6f1c.mp4", "content_type": "video/mp4", "max_bytes": 104857600, "upload_url_expires_at": "2026-09-17T15:07:48.000Z", "url_expires_at": "2026-10-17T14:52:48.000Z" } } } }, "400": { "description": "The body is not a JSON object, or `content_type` is missing or not an accepted image or video type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "`content_type` must be one of: image/jpeg, image/png, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import { readFile } from 'node:fs/promises';\nimport Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\n// Creates the ticket and uploads the file to it.\nconst ticket = await mage.uploads.upload(await readFile('clip.mp4'), {\n contentType: 'video/mp4',\n});\n\nconsole.log(ticket.url); // send this in any media field" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\n# Creates the ticket and uploads the file to it.\nticket = mage.uploads.upload(\"clip.mp4\") # a path, bytes, or a binary file\n\nprint(ticket[\"url\"]) # send this in any media field" } ] } }, "/v1/characters": { "get": { "operationId": "list_characters", "summary": "List characters", "description": "The account's own characters, newest first. Other users' public characters are not listed; they are reached by `@handle` in a prompt.", "tags": [ "Characters" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Entities per page, 1 to 200; 50 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CharacterList" }, "example": { "data": [ { "id": "3f9c2a1e-7b44-4d2e-9a0f-6c1d8e2b5a71", "handle": "ana", "name": "Ana", "description": "A red-haired courier in a green jacket.", "image_url": "https://cdn3.mage.space/characters/user/image/9b1e.jpg", "voice_url": "https://cdn3.mage.space/references/user/audio/7d2c.mp3", "visibility": "private", "created_at": "2026-09-18T10:00:00.000Z" } ], "next_cursor": null } } } }, "400": { "$ref": "#/components/responses/InvalidListRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst page = await mage.characters.list({ limit: 50 });\n\nfor (const character of page.data) {\n console.log(`@${character.handle}`, character.name);\n}\n// Pass page.next_cursor as cursor for the next page." }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\npage = mage.characters.list(limit=50)\n\nfor character in page[\"data\"]:\n print(f\"@{character['handle']}\", character[\"name\"])\n# Pass page[\"next_cursor\"] as cursor for the next page." } ] }, "post": { "operationId": "create_character", "summary": "Create character", "description": "Save a private character from a name, a portrait, and optionally a voice clip. Its `handle` is what a prompt mentions.", "tags": [ "Characters" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCharacterRequest" }, "example": { "name": "Ana", "handle": "ana", "image": "https://example.com/ana.jpg", "description": "A red-haired courier in a green jacket.", "voice": "https://example.com/ana-voice.mp3" } } } }, "responses": { "201": { "description": "The character.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Character" }, "example": { "id": "3f9c2a1e-7b44-4d2e-9a0f-6c1d8e2b5a71", "handle": "ana", "name": "Ana", "description": "A red-haired courier in a green jacket.", "image_url": "https://cdn3.mage.space/characters/user/image/9b1e.jpg", "voice_url": "https://cdn3.mage.space/references/user/audio/7d2c.mp3", "visibility": "private", "created_at": "2026-09-18T10:00:00.000Z" } } } }, "400": { "$ref": "#/components/responses/InvalidCreateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CreateForbidden" }, "409": { "$ref": "#/components/responses/HandleTaken" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nawait mage.characters.create({\n name: 'Ana',\n handle: 'ana',\n image: 'https://example.com/ana.jpg',\n});\n\nawait mage.run('mango', { prompt: '@ana walking through a night market' });" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nmage.characters.create(\n name=\"Ana\",\n handle=\"ana\",\n image=\"https://example.com/ana.jpg\",\n)\n\nmage.run(\"mango\", {\"prompt\": \"@ana walking through a night market\"})" } ] } }, "/v1/characters/{character_id}": { "delete": { "operationId": "delete_character", "summary": "Delete character", "description": "Remove the account's character. Its handle stops resolving at once and may be taken again.", "tags": [ "Characters" ], "parameters": [ { "name": "character_id", "in": "path", "required": true, "description": "The character's `id`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The character was deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CharacterNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nawait mage.characters.delete('CHARACTER_ID');" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nmage.characters.delete(\"CHARACTER_ID\")" } ] } }, "/v1/references": { "get": { "operationId": "list_references", "summary": "List references", "description": "The account's own image and audio references, newest first.", "tags": [ "References" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Entities per page, 1 to 200; 50 when omitted.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of references.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceList" }, "example": { "data": [ { "id": "a81f0c5d-2e6b-4f93-b7c4-0d9e5a3c2f18", "handle": "red-coat", "name": "Red coat", "kind": "outfit", "description": null, "image_url": "https://cdn3.mage.space/references/user/image/4c2d.jpg", "audio_url": null, "created_at": "2026-09-18T10:05:00.000Z" } ], "next_cursor": null } } } }, "400": { "$ref": "#/components/responses/InvalidListRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst page = await mage.references.list({ limit: 50 });\n\nfor (const reference of page.data) {\n console.log(`@${reference.handle}`, reference.kind);\n}" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\npage = mage.references.list(limit=50)\n\nfor reference in page[\"data\"]:\n print(f\"@{reference['handle']}\", reference[\"kind\"])" } ] }, "post": { "operationId": "create_reference", "summary": "Create reference", "description": "Save a private reference: an object, location, pose, or outfit from an image, or an audio reference from a clip. Its `handle` is what a prompt mentions.", "tags": [ "References" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReferenceRequest" }, "example": { "name": "Red coat", "handle": "red-coat", "kind": "outfit", "image": "https://example.com/red-coat.jpg" } } } }, "responses": { "201": { "description": "The reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reference" }, "example": { "id": "a81f0c5d-2e6b-4f93-b7c4-0d9e5a3c2f18", "handle": "red-coat", "name": "Red coat", "kind": "outfit", "description": null, "image_url": "https://cdn3.mage.space/references/user/image/4c2d.jpg", "audio_url": null, "created_at": "2026-09-18T10:05:00.000Z" } } } }, "400": { "$ref": "#/components/responses/InvalidCreateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/CreateForbidden" }, "409": { "$ref": "#/components/responses/HandleTaken" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nawait mage.references.create({\n name: 'Red coat',\n handle: 'red-coat',\n kind: 'outfit',\n image: 'https://example.com/red-coat.jpg',\n});\n\nawait mage.run('mango', { prompt: 'a figure wearing @red-coat in the snow' });" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nmage.references.create(\n name=\"Red coat\",\n handle=\"red-coat\",\n kind=\"outfit\",\n image=\"https://example.com/red-coat.jpg\",\n)\n\nmage.run(\"mango\", {\"prompt\": \"a figure wearing @red-coat in the snow\"})" } ] } }, "/v1/references/{reference_id}": { "delete": { "operationId": "delete_reference", "summary": "Delete reference", "description": "Remove the account's reference. Its handle stops resolving at once and may be taken again.", "tags": [ "References" ], "parameters": [ { "name": "reference_id", "in": "path", "required": true, "description": "The reference's `id`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "The reference was deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ReferenceNotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nawait mage.references.delete('REFERENCE_ID');" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nmage.references.delete(\"REFERENCE_ID\")" } ] } }, "/v1/anima/generate": { "post": { "operationId": "generate_anima", "summary": "Anima", "description": "Generate an image with Anima.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Anima.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "anima-v1" ], "description": "The model variant to generate with.", "default": "anima-v1" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1k", "2k" ], "description": "Output resolution token.", "default": "1k" }, "scheduler": { "type": "string", "default": "euler" }, "shift": { "type": "number", "default": 3 }, "prompt_weighting": { "type": "boolean", "default": true }, "num_inference_steps": { "type": "number", "default": 30 }, "guidance_scale": { "type": "number", "default": 5 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "anima", "model_id": "anima-v1", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 20 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('anima', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"anima\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/chroma/generate": { "post": { "operationId": "generate_chroma", "summary": "Chroma", "description": "Generate an image with Chroma.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Chroma.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "chroma-v1-hd" ], "description": "The model variant to generate with.", "default": "chroma-v1-hd" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "num_inference_steps": { "type": "number", "default": 40 }, "guidance_scale": { "type": "number", "default": 3 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "chroma", "model_id": "chroma-v1-hd", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 35 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('chroma', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"chroma\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/flux2/generate": { "post": { "operationId": "generate_flux2", "summary": "Flux 2", "description": "Generate an image with Flux 2.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Flux 2.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "flux2-dev" ], "description": "The model variant to generate with.", "default": "flux2-dev" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1k", "2k" ], "description": "Output resolution token.", "default": "1k" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "num_inference_steps": { "type": "number", "default": 28 }, "guidance_scale": { "type": "number", "default": 4 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "flux2", "model_id": "flux2-dev", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 40 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('flux2', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"flux2\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/gpt_image_2/generate": { "post": { "operationId": "generate_gpt_image_2", "summary": "GPT Image 2", "description": "Generate an image with GPT Image 2.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for GPT Image 2.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "gpt-image-2", "gpt-image-2.5-flare", "gpt-image-2.5-sunburst" ], "description": "The model variant to generate with.", "default": "gpt-image-2" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1K", "2K" ], "description": "Output resolution token.", "default": "1K" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "quality": { "type": "string", "default": "low" } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "gpt_image_2", "model_id": "gpt-image-2", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 9 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('gpt_image_2', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"gpt_image_2\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/grok_image/generate": { "post": { "operationId": "generate_grok_image", "summary": "Grok Image", "description": "Generate an image with Grok Image.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Grok Image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "grok-imagine-image", "grok-imagine-image-quality", "grok-imagine-image-2.0" ], "description": "The model variant to generate with.", "default": "grok-imagine-image-quality" }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "2:1", "1:2", "19.5:9", "9:19.5", "20:9", "9:20" ], "description": "Aspect ratio as `W:H`.", "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1k", "2k" ], "description": "Output resolution token.", "default": "1k" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "quality": { "type": "string", "default": "medium" } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "1:1" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "grok_image", "model_id": "grok-imagine-image-quality", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 75 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('grok_image', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '1:1',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"grok_image\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"1:1\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/guava/generate": { "post": { "operationId": "generate_guava", "summary": "Guava", "description": "Generate an image with Guava.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Guava.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "guava", "guava-pro", "guava-pro-v1-5", "guava-2", "guava-2-pro" ], "description": "The model variant to generate with.", "default": "guava" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1K", "2K" ], "description": "Output resolution token.", "default": "1K" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "prompt_extend": { "type": "boolean", "default": false } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "guava", "model_id": "guava", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 37 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('guava', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"guava\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/hidream/generate": { "post": { "operationId": "generate_hidream", "summary": "HiDream", "description": "Generate an image with HiDream.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for HiDream.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "hidream-fast" ], "description": "The model variant to generate with.", "default": "hidream-fast" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "negative_prompt": { "type": "string", "default": "" }, "num_inference_steps": { "type": "number", "default": 16 }, "guidance_scale": { "type": "number", "default": 0 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "hidream", "model_id": "hidream-fast", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 20 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('hidream', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"hidream\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/krea_2/generate": { "post": { "operationId": "generate_krea_2", "summary": "Krea 2", "description": "Generate an image with Krea 2.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Krea 2.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "krea-2-turbo" ], "description": "The model variant to generate with.", "default": "krea-2-turbo" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1k", "2k" ], "description": "Output resolution token.", "default": "1k" }, "scheduler": { "type": "string", "default": "euler" }, "num_inference_steps": { "type": "number", "default": 8 }, "guidance_scale": { "type": "number", "default": 0 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "krea_2", "model_id": "krea-2-turbo", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 20 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('krea_2', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"krea_2\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/mango/generate": { "post": { "operationId": "generate_mango", "summary": "Mango", "description": "Generate an image with Mango.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Mango.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "mango", "mango-v2", "mango-v3s", "mango-v3", "mango-v3-turbo" ], "description": "The model variant to generate with.", "default": "mango-v3" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "3K", "4K" ], "description": "Output resolution token.", "default": "2K" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "mango", "model_id": "mango-v3", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 135 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('mango', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"mango\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/nano_banana_v2/generate": { "post": { "operationId": "generate_nano_banana_v2", "summary": "Nano Banana 2", "description": "Generate an image with Nano Banana 2.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Nano Banana 2.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "nano-banana-v2", "nano-banana-v2.1" ], "description": "The model variant to generate with.", "default": "nano-banana-v2.1" }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "3:2", "2:3", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9" ], "description": "Aspect ratio as `W:H`.", "default": "1:1" }, "resolution": { "type": "string", "enum": [ "512", "1K", "2K", "4K" ], "description": "Output resolution token.", "default": "1K" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "thinking_level": { "type": "string", "default": "minimal" }, "web_search": { "type": "boolean", "default": false }, "image_search": { "type": "boolean", "default": false } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "1:1" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "nano_banana_v2", "model_id": "nano-banana-v2.1", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 51 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('nano_banana_v2', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '1:1',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"nano_banana_v2\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"1:1\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/sdxl_plus/generate": { "post": { "operationId": "generate_sdxl_plus", "summary": "SDXL Plus", "description": "Generate an image with SDXL Plus.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for SDXL Plus.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B80" ], "description": "The model variant to generate with.", "default": "6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B80" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "negative_prompt": { "type": "string", "default": "" }, "num_inference_steps": { "type": "number", "default": 50 }, "guidance_scale": { "type": "number", "default": 5 }, "scheduler": { "type": "string", "default": "euler" }, "prompt_embed_version": { "type": "string", "default": "v1" }, "hires": { "type": "boolean", "default": true }, "hires_strength": { "type": "number", "default": 0.5 }, "adetailer_face": { "type": "boolean", "default": true }, "adetailer_face_strength": { "type": "number", "default": 0.4 }, "adetailer_face_blur": { "type": "number", "default": 4 }, "adetailer_face_dilation": { "type": "number", "default": 4 }, "adetailer_hands": { "type": "boolean", "default": true }, "adetailer_hands_strength": { "type": "number", "default": 0.4 }, "adetailer_hands_blur": { "type": "number", "default": 4 }, "adetailer_hands_dilation": { "type": "number", "default": 4 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "sdxl_plus", "model_id": "6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B80", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 15 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('sdxl_plus', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"sdxl_plus\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/stable_diffusion_v15/generate": { "post": { "operationId": "generate_stable_diffusion_v15", "summary": "Stable Diffusion v1.5", "description": "Generate an image with Stable Diffusion v1.5.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Stable Diffusion v1.5.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D" ], "description": "The model variant to generate with.", "default": "15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "negative_prompt": { "type": "string", "default": "" }, "num_inference_steps": { "type": "number", "default": 20 }, "guidance_scale": { "type": "number", "default": 7.5 }, "scheduler": { "type": "string", "default": "kdpm2_karras" } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "stable_diffusion_v15", "model_id": "15012C538F503CE2EBFC2C8547B268C75CCDAFF7A281DB55399940FF1D70E21D", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 10 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('stable_diffusion_v15', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"stable_diffusion_v15\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/stable_diffusion_v35_large/generate": { "post": { "operationId": "generate_stable_diffusion_v35_large", "summary": "Stable Diffusion v3.5 Large", "description": "Generate an image with Stable Diffusion v3.5 Large.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Stable Diffusion v3.5 Large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "sd-3-5-large" ], "description": "The model variant to generate with.", "default": "sd-3-5-large" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "negative_prompt": { "type": "string", "default": "" }, "num_inference_steps": { "type": "number", "default": 28 }, "guidance_scale": { "type": "number", "default": 7.5 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "stable_diffusion_v35_large", "model_id": "sd-3-5-large", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 10 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('stable_diffusion_v35_large', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"stable_diffusion_v35_large\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/stable_diffusion_xl/generate": { "post": { "operationId": "generate_stable_diffusion_xl", "summary": "Stable Diffusion XL", "description": "Generate an image with Stable Diffusion XL.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Stable Diffusion XL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B80" ], "description": "The model variant to generate with.", "default": "6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B80" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "negative_prompt": { "type": "string", "default": "" }, "num_inference_steps": { "type": "number", "default": 30 }, "guidance_scale": { "type": "number", "default": 7 }, "prompt_embed_version": { "type": "string", "default": "v1" } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "stable_diffusion_xl", "model_id": "6A35A7855770AE9820A3C931D4964C3817B6D9E3C6F9C4DABB5B3A94E5643B80", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 10 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('stable_diffusion_xl', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"stable_diffusion_xl\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/z_image/generate": { "post": { "operationId": "generate_z_image", "summary": "Z-Image", "description": "Generate an image with Z-Image.", "tags": [ "Image models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Z-Image.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "z-image-turbo" ], "description": "The model variant to generate with.", "default": "z-image-turbo" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "4:5" }, "resolution": { "type": "string", "enum": [ "1k", "2k" ], "description": "Output resolution token.", "default": "1k" }, "num_inference_steps": { "type": "number", "default": 9 }, "guidance_scale": { "type": "number", "default": 0 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "Editorial portrait in soft daylight, 35mm film look", "aspect_ratio": "4:5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "z_image", "model_id": "z-image-turbo", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 10 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('z_image', {\n prompt: 'Editorial portrait in soft daylight, 35mm film look',\n aspect_ratio: '4:5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"z_image\", {\n \"prompt\": \"Editorial portrait in soft daylight, 35mm film look\",\n \"aspect_ratio\": \"4:5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/berry/generate": { "post": { "operationId": "generate_berry", "summary": "Berry", "description": "Generate a video with Berry.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Berry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "berry", "berry-2" ], "description": "The model variant to generate with.", "default": "berry-2" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "4:5", "5:4" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "1080p", "480p" ], "description": "Output resolution token.", "default": "480p" }, "duration": { "type": "string", "enum": [ "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "description": "Clip length in seconds, as a token.", "default": "3" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "video": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The source video. An https URL or a data URL." } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "3" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "berry", "model_id": "berry-2", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 189 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('berry', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '3',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"berry\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"3\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/blueberry/generate": { "post": { "operationId": "generate_blueberry", "summary": "Blueberry", "description": "Generate a video with Blueberry.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Blueberry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "blueberry", "blueberry-v2" ], "description": "The model variant to generate with.", "default": "blueberry-v2" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ], "description": "Output resolution token.", "default": "720p" }, "duration": { "type": "string", "enum": [ "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "description": "Clip length in seconds, as a token.", "default": "4" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "last_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The last frame image. An https URL or a data URL." }, "shot_type": { "type": "string", "default": "single" }, "prompt_extend": { "type": "boolean", "default": false }, "audio": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "4" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "blueberry", "model_id": "blueberry-v2", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 360 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('blueberry', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '4',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"blueberry\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"4\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/cherry/generate": { "post": { "operationId": "generate_cherry", "summary": "Cherry", "description": "Generate a video with Cherry.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Cherry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "cherry-mini", "cherry", "cherry-pro", "cherry-2-pro" ], "description": "The model variant to generate with.", "default": "cherry-2-pro" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p", "4k" ], "description": "Output resolution token.", "default": "480p" }, "duration": { "type": "string", "enum": [ "4", "5", "8", "10", "15", "20", "25", "30" ], "description": "Clip length in seconds, as a token.", "default": "4" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "videos": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "The source videos. Each an https URL or a data URL." }, "use_character_voices": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "4" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "cherry", "model_id": "cherry-2-pro", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 618 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('cherry', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '4',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"cherry\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"4\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/grok_video/generate": { "post": { "operationId": "generate_grok_video", "summary": "Grok Video", "description": "Generate a video with Grok Video.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Grok Video.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "grok-imagine-video" ], "description": "The model variant to generate with.", "default": "grok-imagine-video" }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p" ], "description": "Output resolution token.", "default": "480p" }, "duration": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "description": "Clip length in seconds, as a token.", "default": "5" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "video": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The source video. An https URL or a data URL." } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "grok_video", "model_id": "grok-imagine-video", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 375 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('grok_video', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"grok_video\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/kiwi/generate": { "post": { "operationId": "generate_kiwi", "summary": "Kiwi", "description": "Generate a video with Kiwi.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Kiwi.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "kiwi" ], "description": "The model variant to generate with.", "default": "kiwi" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p" ], "description": "Output resolution token.", "default": "480p" }, "duration": { "type": "string", "enum": [ "5", "10" ], "description": "Clip length in seconds, as a token.", "default": "5" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "kiwi", "model_id": "kiwi", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 270 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('kiwi', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"kiwi\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/lemon/generate": { "post": { "operationId": "generate_lemon", "summary": "Lemon", "description": "Generate a video with Lemon.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Lemon.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "lemon" ], "description": "The model variant to generate with.", "default": "lemon" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p", "1080p" ], "description": "Output resolution token.", "default": "480p" }, "duration": { "type": "string", "enum": [ "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30" ], "description": "Clip length in seconds, as a token.", "default": "3" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "last_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The last frame image. An https URL or a data URL." }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "videos": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "The source videos. Each an https URL or a data URL." }, "audio": { "type": "boolean", "default": true }, "prompt_extend": { "type": "boolean", "default": false }, "use_character_voices": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "3" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "lemon", "model_id": "lemon", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 245 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('lemon', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '3',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"lemon\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"3\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/ltx_video/generate": { "post": { "operationId": "generate_ltx_video", "summary": "LTX Video", "description": "Generate a video with LTX Video.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for LTX Video.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "ltx-video-096-distilled", "ltx-video-096-dev" ], "description": "The model variant to generate with.", "default": "ltx-video-096-distilled" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "3:2" }, "resolution": { "type": "string", "enum": [ "240p", "360p", "480p", "720p" ], "description": "Output resolution token.", "default": "480p" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "negative_prompt": { "type": "string", "default": "worst quality, inconsistent motion, blurry, jittery, distorted" }, "num_inference_steps": { "type": "number", "default": 8 }, "guidance_scale": { "type": "number", "default": 3 }, "decode_timestep": { "type": "number", "default": 0.05 }, "decode_noise_scale": { "type": "number", "default": 0.025 }, "prompt_enhance": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "3:2" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "ltx_video", "model_id": "ltx-video-096-distilled", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 20 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('ltx_video', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '3:2',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"ltx_video\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"3:2\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/melon/generate": { "post": { "operationId": "generate_melon", "summary": "Melon", "description": "Generate a video with Melon.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Melon.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "melon", "melon-pro" ], "description": "The model variant to generate with.", "default": "melon" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "3:4", "4:3" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "540p", "720p", "1080p" ], "description": "Output resolution token.", "default": "540p" }, "duration": { "type": "string", "enum": [ "3", "4", "5", "6", "8", "10", "16" ], "description": "Clip length in seconds, as a token.", "default": "4" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "last_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The last frame image. An https URL or a data URL." }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "generate_audio": { "type": "boolean", "default": false } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "4" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "melon", "model_id": "melon", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 147 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('melon', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '4',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"melon\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"4\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/minimax_h3/generate": { "post": { "operationId": "generate_minimax_h3", "summary": "MiniMax-H3", "description": "Generate a video with MiniMax-H3.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for MiniMax-H3.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "minimax-h3-turbo", "minimax-h3" ], "description": "The model variant to generate with.", "default": "minimax-h3-turbo" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "544p", "720p", "768p" ], "description": "Output resolution token.", "default": "480p" }, "duration": { "type": "string", "enum": [ "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "description": "Clip length in seconds, as a token.", "default": "5" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "last_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The last frame image. An https URL or a data URL." }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "videos": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "The source videos. Each an https URL or a data URL." }, "use_character_voices": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "minimax_h3", "model_id": "minimax-h3-turbo", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 30 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('minimax_h3', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"minimax_h3\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/plum/generate": { "post": { "operationId": "generate_plum", "summary": "Plum", "description": "Generate a video with Plum.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Plum.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "plum", "plum-max" ], "description": "The model variant to generate with.", "default": "plum-max" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "768P", "2K", "480P" ], "description": "Output resolution token.", "default": "480P" }, "duration": { "type": "string", "enum": [ "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "description": "Clip length in seconds, as a token.", "default": "5" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "last_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The last frame image. An https URL or a data URL." }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "videos": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "The source videos. Each an https URL or a data URL." }, "use_character_voices": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "plum", "model_id": "plum-max", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 338 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('plum', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"plum\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/raspberry/generate": { "post": { "operationId": "generate_raspberry", "summary": "Raspberry", "description": "Generate a video with Raspberry.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Raspberry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "raspberry" ], "description": "The model variant to generate with.", "default": "raspberry" }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ], "description": "Output resolution token.", "default": "720p" }, "duration": { "type": "string", "enum": [ "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" ], "description": "Clip length in seconds, as a token.", "default": "4" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "additional_images": { "type": "array", "items": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": "Additional reference images. Each an https URL or a data URL." }, "use_character_voices": { "type": "boolean", "default": true } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9", "duration": "4" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "raspberry", "model_id": "raspberry", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 360 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('raspberry', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n duration: '4',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"raspberry\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n \"duration\": \"4\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/wan_22/generate": { "post": { "operationId": "generate_wan_22", "summary": "Wan Video v2.2", "description": "Generate a video with Wan Video v2.2.", "tags": [ "Video models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Wan Video v2.2.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "wan22-video", "wan22-video-lightning" ], "description": "The model variant to generate with.", "default": "wan22-video" }, "aspect_ratio": { "type": "string", "enum": [ "21:9", "16:9", "3:2", "5:4", "1:1", "4:5", "2:3", "9:16", "9:21" ], "description": "Aspect ratio as `W:H`.", "default": "16:9" }, "resolution": { "type": "string", "enum": [ "240p", "360p", "480p", "720p" ], "description": "Output resolution token.", "default": "240p" }, "first_image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The first frame image. An https URL or a data URL." }, "negative_prompt": { "type": "string", "default": "" }, "num_inference_steps": { "type": "number", "default": 15 }, "guidance_scale": { "type": "number", "default": 4 }, "flow_shift": { "type": "number", "default": 12 }, "num_frames": { "type": "number", "default": 81 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below", "aspect_ratio": "16:9" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "wan_22", "model_id": "wan22-video", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 40 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('wan_22', {\n prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',\n aspect_ratio: '16:9',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"wan_22\", {\n \"prompt\": \"A slow push-in on a lighthouse at dusk, waves breaking below\",\n \"aspect_ratio\": \"16:9\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } }, "/v1/seed_audio/generate": { "post": { "operationId": "generate_seed_audio", "summary": "Seed Audio", "description": "Generate audio with Seed Audio.", "tags": [ "Audio models" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with `200` instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries `request_id`) replays the same way, so a new attempt needs a new key.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "description": "A partial config for Seed Audio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt." }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Integer seed for reproducible output; omit or send null for a random seed." }, "model_id": { "type": "string", "enum": [ "seed-audio-1.0" ], "description": "The model variant to generate with.", "default": "seed-audio-1.0" }, "duration": { "type": "string", "enum": [ "5", "10", "30", "60", "120" ], "description": "Clip length in seconds, as a token.", "default": "5" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The reference image. An https URL or a data URL." }, "sample_rate": { "type": "number", "default": 48000 }, "speech_rate": { "type": "number", "default": 0 }, "loudness_rate": { "type": "number", "default": 0 }, "pitch_rate": { "type": "number", "default": 0 } }, "required": [ "prompt" ], "additionalProperties": true }, "example": { "prompt": "A calm narrator reading a short weather report", "duration": "5" } } } }, "responses": { "202": { "description": "The request was accepted; poll `status_url` for the result. A retried submit whose `Idempotency-Key` was used before answers `200` with the same shape, the original request, and charges nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" }, "example": { "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "status": "in_progress", "architecture": "seed_audio", "model_id": "seed-audio-1.0", "created_at": "2026-09-17T14:52:48.000Z", "updated_at": "2026-09-17T14:52:49.000Z", "billing": { "mode": "gems", "gems_charged": 19 }, "result": null, "error": null, "status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status", "cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel" } } } }, "400": { "$ref": "#/components/responses/InvalidGenerateRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientGems" }, "403": { "$ref": "#/components/responses/GenerationForbidden" }, "410": { "$ref": "#/components/responses/ArchitectureRetired" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "451": { "$ref": "#/components/responses/ExternalContentBlock" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import Mage from '@mage-space/sdk';\n\nconst mage = new Mage(); // reads MAGE_API_KEY\n\nconst request = await mage.run('seed_audio', {\n prompt: 'A calm narrator reading a short weather report',\n duration: '5',\n});\n\nconsole.log(request.result.url);" }, { "lang": "python", "label": "Python SDK", "source": "from mage_space import Mage\n\nmage = Mage() # reads MAGE_API_KEY\n\nrequest = mage.run(\"seed_audio\", {\n \"prompt\": \"A calm narrator reading a short weather report\",\n \"duration\": \"5\",\n})\n\nprint(request[\"result\"][\"url\"])" } ] } } }, "components": { "responses": { "Unauthorized": { "description": "The key is missing, malformed, unknown, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "The API key is invalid or has been revoked." } } } } }, "InternalError": { "description": "Something failed on Mage's side. Retry, and contact support if it persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side. Retry, and contact support if it persists." } } } } }, "RequestNotFound": { "description": "No request with this id belongs to the account, or it was not made through the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "request_not_found", "message": "No request with this id belongs to the account." } } } } }, "InvalidGenerateRequest": { "description": "The body is not a JSON object, sets a server-owned field, contradicts the architecture, breaks a field's type or token list, mentions an `@handle` that does not resolve or that the model does not support, exceeds the image or audio budget, or breaks a model rule; or the `Idempotency-Key` is malformed. `invalid_config` names the field, the handle, or the rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_config", "message": "`resolution` must be one of: 768P, 2K." } } } } }, "InvalidListRequest": { "description": "`limit` is not a whole number in range, or `cursor` is not a `next_cursor` from an earlier page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "`limit` must be a whole number from 1 to 200." } } } } }, "InvalidCreateRequest": { "description": "The body is not a JSON object, a required field is missing, a value is out of range, `handle` breaks the handle rules, or a media source could not be fetched or is not an accepted format. The message names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "`name` is required." } } } } }, "CreateForbidden": { "description": "The account cannot create characters or references.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "This account cannot create characters or references." } } } } }, "HandleTaken": { "description": "A live character or reference already uses the handle. Choose another, or omit `handle` to derive one from the name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "handle_taken", "message": "The handle `@ana` is taken. Choose another, or omit `handle` to derive one from the name.", "handle": "ana" } } } } }, "CharacterNotFound": { "description": "No character with this id belongs to the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "character_not_found", "message": "No character with this id belongs to the account." } } } } }, "ReferenceNotFound": { "description": "No reference with this id belongs to the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "reference_not_found", "message": "No reference with this id belongs to the account." } } } } }, "InsufficientGems": { "description": "The gems balance is below the price. `gems_required` is the price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_gems", "message": "This generation costs 40 gems and the account balance is too low.", "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff", "gems_required": 40 } } } } }, "GenerationForbidden": { "description": "The account cannot generate (`forbidden`), or the request was blocked by the content policy before it ran (`content_blocked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "content_blocked", "message": "The request was blocked by Mage's content policy.", "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff" } } } } }, "ArchitectureRetired": { "description": "The architecture has been retired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "architecture_retired", "message": "This architecture has been retired.", "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff" } } } } }, "TooManyRequests": { "description": "The account already has its cap of generations in flight (20 unless set otherwise for the account), web and API together. Wait for some to finish.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "too_many_requests", "message": "At most 20 generations may be in flight at once for this account; 20 are running now." } } } } }, "ExternalContentBlock": { "description": "The request was blocked by an external content restriction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "content_blocked", "message": "The request was blocked by an external content restriction.", "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff" } } } } } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Create a key in [API → API Keys](https://www.mage.space/api?tab=api-keys): select **Create API key**, name it in the popup, then select **Create key**. Copy the one-time key and send it as `Authorization: Bearer mage_sk_…`. Keys are for server-side code only." } }, "schemas": { "Request": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "The request id, also the id in `status_url` and `cancel_url`." }, "status": { "type": "string", "enum": [ "queued", "in_progress", "completed", "failed", "cancelled" ], "description": "`queued` and `in_progress` are live; `completed`, `failed`, and `cancelled` are final." }, "architecture": { "type": "string", "description": "The architecture the request generates with." }, "model_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The model variant, when the architecture has variants." }, "created_at": { "type": "string", "format": "date-time", "description": "When the request was accepted." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the request last changed." }, "billing": { "type": "object", "properties": { "mode": { "type": "string", "const": "gems", "description": "Every API request is paid in gems." }, "gems_charged": { "type": "number", "description": "Gems debited for the request." }, "gems_refunded": { "description": "Gems returned to the account; present on failed requests.", "type": "number" } }, "required": [ "mode", "gems_charged" ], "additionalProperties": false }, "result": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio" ], "description": "The media type of the output." }, "url": { "type": "string", "format": "uri", "description": "Where to download the output." }, "width": { "type": "integer", "description": "Output width in pixels; 0 for audio." }, "height": { "type": "integer", "description": "Output height in pixels; 0 for audio." }, "seed": { "type": "integer", "description": "The seed the generation ran with." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When `url` stops working: 30 days after the request for temporary media, or null for permanent media." }, "moderation": { "type": "object", "properties": { "nsfw": { "type": "boolean", "description": "Whether moderation flagged the output as NSFW." } }, "required": [ "nsfw" ], "additionalProperties": false, "description": "Moderation flags on the output." } }, "required": [ "type", "url", "width", "height", "seed", "expires_at", "moderation" ], "additionalProperties": false }, { "type": "null" } ], "description": "The output once `status` is `completed`, else null." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_request", "invalid_config", "architecture_not_found", "architecture_retired", "request_not_found", "character_not_found", "reference_not_found", "not_found", "insufficient_gems", "forbidden", "content_blocked", "request_finished", "handle_taken", "too_many_requests", "generation_failed", "internal_error" ], "description": "A stable error code." }, "message": { "type": "string", "description": "What went wrong, for a person." } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the request failed once `status` is `failed`, else null." }, "status_url": { "type": "string", "format": "uri", "description": "Poll this URL for the request." }, "cancel_url": { "type": "string", "format": "uri", "description": "POST to this URL to stop the request." } }, "required": [ "request_id", "status", "architecture", "model_id", "created_at", "updated_at", "billing", "result", "error", "status_url", "cancel_url" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "invalid_request", "invalid_config", "architecture_not_found", "architecture_retired", "request_not_found", "character_not_found", "reference_not_found", "not_found", "insufficient_gems", "forbidden", "content_blocked", "request_finished", "handle_taken", "too_many_requests", "generation_failed", "internal_error" ], "description": "A stable error code; treat an unknown code by its HTTP status." }, "message": { "type": "string", "description": "What went wrong, for a person." }, "request_id": { "description": "The request the refusal belongs to, when one was recorded before the refusal.", "type": "string", "format": "uuid" }, "gems_required": { "description": "The price of the refused generation, on `insufficient_gems`.", "type": "number" }, "docs_url": { "description": "Where to read the API reference, on `not_found`.", "type": "string", "format": "uri" }, "handle": { "description": "The handle that is taken, on `handle_taken`.", "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": true, "description": "Further fields depend on the code." } }, "required": [ "error" ], "additionalProperties": false }, "GenerateRequest": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "description": "The text prompt. An `@handle` in it attaches one of your saved characters or references." }, "model_id": { "description": "The model variant; the architecture default when omitted.", "type": "string" }, "seed": { "description": "Integer seed for reproducible output; omit or send null for a random seed.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "aspect_ratio": { "description": "The output aspect ratio as `W:H` (`16:9`), on models that have one; each model lists its ratios.", "type": "string" }, "first_image": { "description": "The first frame image, on models that start a video from one. An https URL or a data URL.", "type": "string" }, "last_image": { "description": "The last frame image, on models that end a video on one. An https URL or a data URL.", "type": "string" }, "resolution": { "description": "The output resolution token, on models that offer one; each model lists its tokens.", "type": "string" }, "duration": { "description": "The clip length in seconds as a token, on video and audio models that offer one; each model lists its tokens.", "type": "string" } }, "required": [ "prompt" ], "additionalProperties": true }, "ArchitectureList": { "type": "object", "properties": { "architectures": { "type": "array", "items": { "$ref": "#/components/schemas/Architecture" } } }, "required": [ "architectures" ] }, "Architecture": { "type": "object", "properties": { "id": { "type": "string", "description": "The architecture id, as used in its endpoint path." }, "name": { "type": "string", "description": "The display name." }, "type": { "type": "string", "enum": [ "image", "video", "audio" ], "description": "What the architecture generates." }, "description": { "type": "string", "description": "What the model is for and its usage rules." }, "image_inputs": { "type": "object", "properties": { "first_frame": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The field a first frame image goes in, or null." }, "last_frame": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The field a last frame image goes in, or null." }, "references": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "description": "The field the first reference image goes in." }, "additional_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The list field further reference images go in, or null." } }, "required": [ "field", "additional_field" ], "additionalProperties": false }, { "type": "null" } ], "description": "Reference image fields, or null when the architecture takes none." } }, "required": [ "first_frame", "last_frame", "references" ], "additionalProperties": false, "description": "The request field for each image role; an absent role is not supported." }, "video_inputs": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "description": "The field holding the source video or videos." } }, "required": [ "field" ], "additionalProperties": false }, { "type": "null" } ], "description": "The source-video field, or null when the architecture takes no video." }, "base_config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": true, "description": "The default config every request starts from." }, "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Allowed tokens per adjustable field, across all variants." }, "options_by_model": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "description": "Per-variant narrowing of `options`, keyed by `model_id`; empty when variants share the lists." }, "mentions": { "type": "object", "properties": { "characters": { "type": "array", "items": { "type": "string" }, "description": "Model ids whose prompts may mention `@character` handles; empty when none may." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Model ids whose prompts may mention image `@reference` handles; empty when none may." }, "audio_references": { "type": "array", "items": { "type": "string" }, "description": "Model ids whose prompts may mention audio `@reference` handles; empty when none may." }, "max_audio_references": { "type": "integer", "description": "Audio references per request. On a model that also sends character voices, the voices share these slots. 0 when the model takes no audio references, which does not stop it sending voices." }, "character_voices": { "type": "boolean", "description": "Whether a mentioned character's voice is sent with its image, unless the request sets `use_character_voices` to false." } }, "required": [ "characters", "references", "audio_references", "max_audio_references", "character_voices" ], "additionalProperties": false, "description": "Which saved characters and references a prompt may mention by `@handle`, per model variant." }, "max_images": { "type": "integer", "description": "Image inputs, characters, and references per request, which share one budget." }, "max_images_by_model": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer" }, "description": "Per-variant overrides of `max_images`, keyed by `model_id`; empty when every variant shares it." }, "input_schema": { "type": "object", "properties": { "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": true } }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "properties", "required" ], "additionalProperties": true, "description": "The request body as JSON Schema (draft 2020-12), defaults folded in." }, "gems": { "type": "number", "description": "The gem price of the default config." }, "generate_url": { "type": "string", "format": "uri", "description": "The endpoint to submit a generation to." } }, "required": [ "id", "name", "type", "description", "image_inputs", "video_inputs", "base_config", "options", "options_by_model", "mentions", "max_images", "max_images_by_model", "input_schema", "gems", "generate_url" ], "additionalProperties": false }, "Account": { "type": "object", "properties": { "gems": { "type": "object", "properties": { "balance": { "type": "number", "description": "Gems available to the account." } }, "required": [ "balance" ], "additionalProperties": false } }, "required": [ "gems" ], "additionalProperties": false }, "UploadRequest": { "type": "object", "properties": { "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "video/mp4", "video/quicktime", "video/webm", "audio/mpeg", "audio/mp3", "audio/wav", "audio/wave", "audio/x-wav" ], "description": "The media type of the file you will upload: an image or video for a generate request, or an audio clip for a character voice or an audio reference." } }, "required": [ "content_type" ], "additionalProperties": false }, "UploadTicket": { "type": "object", "properties": { "upload_url": { "type": "string", "format": "uri", "description": "PUT the file here." }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Headers the PUT must carry exactly; storage checks them against the signature." }, "url": { "type": "string", "format": "uri", "description": "The URL the file has once the PUT succeeds. Send it in any media field, or as `voice` or `audio` when creating a character or an audio reference." }, "content_type": { "type": "string", "description": "The media type the PUT must declare." }, "max_bytes": { "type": "integer", "description": "The largest body the upload accepts: 100 MB." }, "upload_url_expires_at": { "type": "string", "format": "date-time", "description": "When `upload_url` stops accepting the PUT." }, "url_expires_at": { "type": "string", "format": "date-time", "description": "When the uploaded file is deleted: 30 days after the ticket." } }, "required": [ "upload_url", "method", "headers", "url", "content_type", "max_bytes", "upload_url_expires_at", "url_expires_at" ], "additionalProperties": false }, "Character": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The character id, as `DELETE /v1/characters/{character_id}` takes it." }, "handle": { "type": "string", "description": "Mention the character in a prompt as `@handle`." }, "name": { "type": "string", "description": "The display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your notes, or null." }, "image_url": { "type": "string", "format": "uri", "description": "The portrait." }, "voice_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The processed voice clip, or null for a character without one." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "Characters created through the API are private; publishing happens in the app." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } }, "required": [ "id", "handle", "name", "description", "image_url", "voice_url", "visibility", "created_at" ], "additionalProperties": false }, "CharacterList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The character id, as `DELETE /v1/characters/{character_id}` takes it." }, "handle": { "type": "string", "description": "Mention the character in a prompt as `@handle`." }, "name": { "type": "string", "description": "The display name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your notes, or null." }, "image_url": { "type": "string", "format": "uri", "description": "The portrait." }, "voice_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The processed voice clip, or null for a character without one." }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "Characters created through the API are private; publishing happens in the app." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } }, "required": [ "id", "handle", "name", "description", "image_url", "voice_url", "visibility", "created_at" ], "additionalProperties": false }, "description": "The page, newest first." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Send as `cursor` for the next page; null on the last page." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "CreateCharacterRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The display name." }, "handle": { "description": "The `@handle` prompts mention it by: 1 to 15 lowercase letters, digits, underscores, or dashes, starting with a letter. Handles such as image1 and image2 are reserved for uploaded images. Derived from the name when omitted. Cannot be changed later.", "type": "string" }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ], "description": "The portrait: an https URL, an upload URL, or a data URL of a JPEG or PNG. Stored permanently with the character." }, "description": { "description": "Optional notes, for your own reference.", "type": "string", "maxLength": 500 }, "voice": { "description": "Optional voice clip: an https URL, an upload URL, or a data URL of an MP3 or WAV. Trimmed to 10 seconds and normalized, like a clip uploaded in the app.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] } }, "required": [ "name", "image" ], "additionalProperties": false }, "Reference": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The reference id, as `DELETE /v1/references/{reference_id}` takes it." }, "handle": { "type": "string", "description": "Mention the reference in a prompt as `@handle`." }, "name": { "type": "string", "description": "The display name." }, "kind": { "type": "string", "enum": [ "object", "location", "pose", "outfit", "audio" ], "description": "What the reference is." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your notes, or null." }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The image, for the four image kinds; null for an audio reference." }, "audio_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The processed clip, for `kind: \"audio\"`; null otherwise." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } }, "required": [ "id", "handle", "name", "kind", "description", "image_url", "audio_url", "created_at" ], "additionalProperties": false }, "ReferenceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The reference id, as `DELETE /v1/references/{reference_id}` takes it." }, "handle": { "type": "string", "description": "Mention the reference in a prompt as `@handle`." }, "name": { "type": "string", "description": "The display name." }, "kind": { "type": "string", "enum": [ "object", "location", "pose", "outfit", "audio" ], "description": "What the reference is." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your notes, or null." }, "image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The image, for the four image kinds; null for an audio reference." }, "audio_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "The processed clip, for `kind: \"audio\"`; null otherwise." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created." } }, "required": [ "id", "handle", "name", "kind", "description", "image_url", "audio_url", "created_at" ], "additionalProperties": false }, "description": "The page, newest first." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Send as `cursor` for the next page; null on the last page." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "CreateReferenceRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "The display name." }, "handle": { "description": "The `@handle` prompts mention it by: 1 to 15 lowercase letters, digits, underscores, or dashes, starting with a letter. Handles such as image1 and image2 are reserved for uploaded images. Derived from the name when omitted. Cannot be changed later.", "type": "string" }, "kind": { "type": "string", "enum": [ "object", "location", "pose", "outfit", "audio" ], "description": "What the reference is. The four image kinds take `image`; `audio` takes `audio`." }, "image": { "description": "The image, for the four image kinds: an https URL, an upload URL, or a data URL of a JPEG or PNG. Stored permanently with the reference.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "audio": { "description": "The clip, for `kind: \"audio\"`: an https URL, an upload URL, or a data URL of an MP3 or WAV. Trimmed to 15 seconds and normalized, like a clip uploaded in the app.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:[^;,]+(?:;[^;,]+)*;base64," } ] }, "description": { "description": "Optional notes, for your own reference.", "type": "string", "maxLength": 500 } }, "required": [ "name", "kind" ], "additionalProperties": false } } } }