{"openapi":"3.0.1","info":{"title":"Magi OpenAPI","description":"API Documentation for Magi. Base URL: https://api.sand.ai\n","version":"1.0"},"servers":[{"url":"https://platform.sand.ai","description":"Generated server url"}],"security":[{"api-key":[]}],"paths":{"/v1/generations":{"post":{"tags":["Generations"],"summary":"Submit video generation","operationId":"generate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequestVo"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/IDOnlyResponse"}}}}},"x-codeSamples":[{"label":"cURL (Magi Image)","source":"curl -X POST \"https://api.sand.ai/v1/generations\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"magi\",\n    \"seed\": 12345,\n    \"aspectRatio\": \"16:9\",\n    \"source\": {\n      \"type\": \"image\",\n      \"content\": 123\n    },\n    \"chunks\": [{\n      \"duration\": 5,\n      \"conditions\": [{\n        \"type\": \"text\",\n        \"content\": \"A beautiful sunset over mountains\"\n      }],\n      \"enablePromptEnhancement\": true\n    }]\n  }'\n","lang":"shell"},{"label":"cURL (Magi-2 Text)","source":"curl -X POST \"https://api.sand.ai/v1/generations\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"magi-2-preview\",\n    \"seed\": 12345,\n    \"resolution\": \"1080p\",\n    \"aspectRatio\": \"16:9\",\n    \"guidance_scale\": 7.5,\n    \"inference_steps\": 64,\n    \"chunks\": [{\n      \"duration\": 10,\n      \"conditions\": [{\n        \"type\": \"text\",\n        \"content\": \"A cinematic aerial view of waves breaking over black sand\"\n      }]\n    }]\n  }'\n","lang":"shell"},{"label":"cURL (Magi-2 Image)","source":"curl -X POST \"https://api.sand.ai/v1/generations\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"magi-2-preview\",\n    \"seed\": 12345,\n    \"resolution\": \"1080p\",\n    \"aspectRatio\": \"16:9\",\n    \"guidance_scale\": 7.5,\n    \"inference_steps\": 64,\n    \"source\": {\n      \"type\": \"image\",\n      \"content\": 123\n    },\n    \"chunks\": [{\n      \"duration\": 10,\n      \"conditions\": [{\n        \"type\": \"text\",\n        \"content\": \"Bring the reference image to life with subtle cinematic motion\"\n      }]\n    }]\n  }'\n","lang":"shell"},{"label":"JavaScript","source":"const requestBody = {\n  model: \"magi\",\n  seed: 12345,\n  aspectRatio: \"16:9\",\n  source: {\n    type: \"image\",\n    content: 123\n  },\n  chunks: [{\n    duration: 5,\n    conditions: [{\n      type: \"text\",\n      content: \"A beautiful sunset over mountains\"\n    }],\n    enablePromptEnhancement: true\n  }]\n};\n\nfetch('https://api.sand.ai/v1/generations', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(requestBody)\n})\n.then(response => response.json())\n.then(data => console.log(data));\n","lang":"javascript"},{"label":"Python","source":"import requests\nimport json\n\nurl = \"https://api.sand.ai/v1/generations\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n}\ndata = {\n    \"model\": \"magi\",\n    \"seed\": 12345,\n    \"aspectRatio\": \"16:9\",\n    \"source\": {\n        \"type\": \"image\",\n        \"content\": 123\n    },\n    \"chunks\": [{\n        \"duration\": 5,\n        \"conditions\": [{\n            \"type\": \"text\",\n            \"content\": \"A beautiful sunset over mountains\"\n        }],\n        \"enablePromptEnhancement\": True\n    }]\n}\n\nresponse = requests.post(url, headers=headers, json=data)\nprint(response.json())\n","lang":"python"}]}},"/v1/assets":{"post":{"tags":["Assets"],"summary":"Upload asset","description":"Upload an image, video, or audio asset.","operationId":"uploadAsset","requestBody":{"content":{"application/json":{"schema":{"required":["file"],"type":"object","properties":{"file":{"type":"string","description":"The file to upload. Supported filename extensions: jpg, jpeg, png, webp, mp4, ts, wav, mp3, aac, and flac.","format":"binary"}}}}}},"responses":{"200":{"description":"The uploaded asset ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IDOnlyResponse"}}}}},"x-codeSamples":[{"label":"cURL","source":"curl -X POST \"https://api.sand.ai/v1/assets\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: multipart/form-data\" \\\n  -F \"file=@/path/to/your/video.mp4\"\n","lang":"shell"},{"label":"JavaScript","source":"const formData = new FormData();\nformData.append('file', fileInput.files[0]);\n\nfetch('https://api.sand.ai/v1/assets', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY'\n  },\n  body: formData\n})\n.then(response => response.json())\n.then(data => console.log(data));\n","lang":"javascript"},{"label":"Python","source":"import requests\n\nurl = \"https://api.sand.ai/v1/assets\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\"\n}\nfiles = {\n    \"file\": open(\"/path/to/your/video.mp4\", \"rb\")\n}\n\nresponse = requests.post(url, headers=headers, files=files)\nprint(response.json())\n","lang":"python"}]}},"/v1/generations/{id}":{"get":{"tags":["Generations"],"summary":"Get video generation status","description":"Get the status and the result video of a video generation task.","operationId":"getGenerationDetail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GenerationResponseVo"}}}}},"x-codeSamples":[{"label":"cURL","source":"curl -X GET \"https://api.sand.ai/v1/generations/123\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n","lang":"shell"},{"label":"JavaScript","source":"fetch('https://api.sand.ai/v1/generations/123', {\n  method: 'GET',\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY'\n  }\n})\n.then(response => response.json())\n.then(data => console.log(data));\n","lang":"javascript"},{"label":"Python","source":"import requests\n\nurl = \"https://api.sand.ai/v1/generations/123\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())\n","lang":"python"}]}},"/v1/assets/{id}":{"get":{"tags":["Assets"],"summary":"Get asset info","description":"Get an asset owned by the organization associated with the current API key. The returned URL is valid for 60 minutes.","operationId":"getAssetById","parameters":[{"name":"id","in":"path","description":"ID of the asset to retrieve.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"The asset ID and temporary access URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformAssetView"}}}}},"x-codeSamples":[{"label":"cURL","source":"curl -X GET \"https://api.sand.ai/v1/assets/123\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n","lang":"shell"},{"label":"JavaScript","source":"fetch('https://api.sand.ai/v1/assets/123', {\n  method: 'GET',\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY'\n  }\n})\n.then(response => response.json())\n.then(data => console.log(data));\n","lang":"javascript"},{"label":"Python","source":"import requests\n\nurl = \"https://api.sand.ai/v1/assets/123\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())\n","lang":"python"}]},"delete":{"tags":["Assets"],"summary":"Delete asset","description":"Delete an asset owned by the organization associated with the current API key.","operationId":"deleteAssetById","parameters":[{"name":"id","in":"path","description":"ID of the asset to delete.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"The deleted asset ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IDOnlyResponse"}}}}},"x-codeSamples":[{"label":"cURL","source":"curl -X DELETE \"https://api.sand.ai/v1/assets/123\" \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n","lang":"shell"},{"label":"JavaScript","source":"fetch('https://api.sand.ai/v1/assets/123', {\n  method: 'DELETE',\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY'\n  }\n})\n.then(response => response.json())\n.then(data => console.log(data));\n","lang":"javascript"},{"label":"Python","source":"import requests\n\nurl = \"https://api.sand.ai/v1/assets/123\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_API_KEY\"\n}\n\nresponse = requests.delete(url, headers=headers)\nprint(response.json())\n","lang":"python"}]}}},"components":{"schemas":{"Chunk":{"type":"object","properties":{"duration":{"type":"integer","description":"Requested video duration in seconds. Exactly one chunk is supported per request.\n\n- **magi**: uses the requested duration.\n- **magi-2-preview**: only supports 10 seconds.\n","format":"int32","example":10},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"}},"enablePromptEnhancement":{"type":"boolean","description":"Whether to enhance the text prompt before generation.\n\n- **magi**: uses the supplied value.\n- **magi-2-preview**: prompt enhancement is enabled by default; an explicit request value overrides the default.\n","example":true}}},"Condition":{"type":"object","properties":{"type":{"type":"string","description":"Condition content type. No video generation task type needs to be supplied.","example":"text","enum":["text"]},"content":{"type":"object","description":"Condition content.\n\n- **text**: prompt text.\n\n**magi** and **magi-2-preview** use a text condition. Audio conditions are not supported.\n","example":"A cinematic landscape"}}},"GenerationRequestVo":{"required":["chunks"],"type":"object","properties":{"model":{"type":"string","description":"Model used for video generation. The default is magi.\n\n**Currently, only magi is publicly available. To use magi-2-preview, please contact us.**\n","example":"magi","enum":["magi","magi-2-preview"]},"seed":{"type":"integer","description":"Random seed passed to the selected generation model.","format":"int64","example":12345},"aspectRatio":{"type":"string","description":"Output video aspect ratio in width:height format.\n\n- **magi**: supports any aspect ratio.\n- **magi-2-preview**: only supports 16:9.\n","example":"16:9"},"resolution":{"type":"string","description":"Output video resolution.\n\n- **magi**: always uses 720p; the request value is ignored.\n- **magi-2-preview**: supports 540p, 720p, and 1080p.\n","example":"1080p","enum":["540p","720p","1080p"]},"source":{"$ref":"#/components/schemas/SourceCondition"},"chunks":{"type":"array","items":{"$ref":"#/components/schemas/Chunk"}},"guidance_scale":{"type":"number","description":"Guidance scale used by Magi-2 generation.\n\nOnly applies to **magi-2-preview**; it is ignored by the default Magi model. No range restriction is currently imposed, and 7.5 has been verified.\n","format":"double","example":7.5},"inference_steps":{"type":"integer","description":"Number of inference steps used by Magi-2 generation.\n\nOnly applies to **magi-2-preview**. The supported range is 4 to 100 and the value must be divisible by 4. The default is 64 when omitted.\n","format":"int32","example":64}}},"SourceCondition":{"type":"object","properties":{"type":{"type":"string","description":"Reference asset media type.\n\n**magi** requires an image or video source. **magi-2-preview** accepts an image source or an omitted source for text-only generation.\n","example":"image","enum":["image","video"]},"content":{"type":"object","description":"Reference Asset ID. The server determines the generation mode automatically from the source asset.","example":"123456789"}}},"IDOnlyResponse":{"type":"object","properties":{"id":{"type":"integer","format":"int64"}}},"AudioGenerateRequestVo":{"required":["text","voiceId"],"type":"object","properties":{"voiceId":{"type":"integer","format":"int64"},"text":{"type":"string"}}},"AudioGenerateResponseVo":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"duration":{"type":"number","format":"double"},"url":{"type":"string"}}},"GenerationResponseVo":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["PreProcessing","Pending","Running","Success","Fail","Canceled"]},"resultVideoURL":{"type":"string"},"resultVideoId":{"type":"integer","format":"int64"},"createTime":{"type":"string","format":"date-time"}}},"PlatformAssetView":{"type":"object","properties":{"id":{"type":"integer","description":"Asset ID.","format":"int64","example":123456789},"url":{"type":"string","description":"Temporary URL for accessing the asset. The URL is valid for 60 minutes."}}}},"securitySchemes":{"api-key":{"type":"apiKey","name":"Authorization","in":"header","bearerFormat":"bearer"}}}}