{ "openapi": "3.1.0", "info": { "title": "MoonApiX API", "version": "0.1.0", "description": "MoonApiX public API specification." }, "servers": [ { "url": "https://moonapix.com", "description": "Recommended primary endpoint" }, { "url": "https://moonapi.yuezhuoxing.com", "description": "Domestic long-request backup endpoint" }, { "url": "https://api.yuezhuoxing.com", "description": "Domestic accelerated backup endpoint" } ], "tags": [ { "name": "Models", "description": "Available models and capabilities" }, { "name": "OpenAI-compatible", "description": "OpenAI-compatible generation endpoints" }, { "name": "Images", "description": "Image generation endpoints" }, { "name": "Videos", "description": "Video generation task endpoints" }, { "name": "Tasks", "description": "Async task query endpoints" }, { "name": "Assets", "description": "Reusable user asset endpoints" }, { "name": "Identity Verification", "description": "Session-based real-person liveness verification and verified asset groups" }, { "name": "Digital Human", "description": "Digital human avatar, voice, audio, and video endpoints" }, { "name": "Music", "description": "Music and lyrics task endpoints" }, { "name": "Audio", "description": "OpenAI-compatible audio endpoints" }, { "name": "Embeddings", "description": "OpenAI-compatible embedding endpoints" }, { "name": "Responses", "description": "OpenAI-compatible response endpoints" }, { "name": "Messages", "description": "Claude-compatible message endpoints" }, { "name": "Gemini", "description": "Gemini-compatible generation endpoints" }, { "name": "Web", "description": "Web search and reader endpoints" }, { "name": "Ideogram", "description": "Ideogram image endpoints" }, { "name": "Midjourney", "description": "Midjourney task endpoints" }, { "name": "Video Compatibility", "description": "Video compatibility endpoints" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Use `Authorization: Bearer `." } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ] } }, "required": [ "error" ] }, "Model": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "seedance-2.0-kz-fast" ] }, "object": { "type": "string", "examples": [ "model" ] }, "owned_by": { "type": "string", "examples": [ "moonapix" ] } }, "required": [ "id", "object" ] }, "ChatMessage": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] } }, "required": [ "role", "content" ] }, "Task": { "type": "object", "properties": { "id": { "type": "string", "description": "MoonApiX public task ID. Use the ID returned on creation for video task queries.", "examples": [ "task_01HX..." ] }, "object": { "type": "string", "examples": [ "task" ] }, "status": { "type": "string", "enum": [ "pending", "submitted", "running", "succeeded", "failed", "cancelled" ] }, "model": { "type": "string" }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/TaskOutputItem" } }, "content": { "$ref": "#/components/schemas/VideoTaskContent" }, "error": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "null" } ] }, "trace_id": { "type": "string", "description": "MoonApiX request trace ID. Provide this value when asking MoonApiX to troubleshoot a task." }, "request_id": { "type": "string", "description": "MoonApiX request ID. Usually the same as trace_id." }, "task_chain": { "type": "array", "description": "Customer-facing task chain summary, such as generation, result URL policy, and asset preparation steps.", "items": { "$ref": "#/components/schemas/TaskChainStep" } }, "result_url": { "type": "string", "format": "uri", "description": "Customer-usable final media URL when the endpoint exposes a top-level result URL. The URL may be an approved direct media URL or a MoonApiX-managed URL. Preserve the complete returned URL, including signed query parameters, and download temporary URLs promptly." } }, "required": [ "id", "status" ], "example": { "id": "task_xxx", "object": "task", "trace_id": "2026060301010100000000000000000000", "request_id": "2026060301010100000000000000000000", "status": "succeeded", "model": "seedance-2.0-kz-fast", "created_at": 1710000000, "result_url": "https://example.com/result.mp4", "output": [ { "type": "video", "url": "https://example.com/result.mp4" } ], "task_chain": [ { "step": "generation", "status": "succeeded", "result_url": "https://example.com/result.mp4" }, { "step": "result_url_policy", "status": "direct_return", "result_url_policy": "direct_return", "result_url": "https://example.com/result.mp4" } ], "error": null } }, "Asset": { "type": "object", "description": "Legacy or compatibility asset response. The typed storage and preparation fields are active for enabled three-layer uploads. Historical unmigrated records retain their existing status semantics; do not reinterpret every historical ready value as the new identity contract. The schema example is a historical legacy projection without an explicit model scope. Explicit v2 responses use AssetV2.", "properties": { "object": { "type": "string", "examples": [ "asset" ], "description": "Object type." }, "id": { "type": "string", "examples": [ "asset_xxx" ], "description": "Customer stable asset ID." }, "asset_id": { "type": "string", "examples": [ "asset_xxx" ], "description": "Customer stable asset ID, same as id." }, "group_id": { "type": "string", "examples": [ "group_xxx" ], "description": "Asset group ID. Assets in different groups are isolated for list and detail queries." }, "domain": { "type": "string", "examples": [ "media" ], "description": "Asset domain or usage area." }, "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ], "description": "Asset type." }, "asset_type": { "type": "string", "examples": [ "image" ], "description": "Asset type alias returned by some compatibility responses." }, "name": { "type": "string", "description": "Asset name." }, "description": { "type": "string", "description": "Asset description." }, "source_url": { "type": "string", "format": "uri", "description": "Legacy URL alias. In an enabled three-layer compatibility upload it contains only a verified, safe managed URL; the original input URL is not returned. Historical responses may retain their earlier URL meaning." }, "url": { "type": "string", "format": "uri", "description": "Customer-usable URL alias. An enabled three-layer compatibility upload returns only a verified managed URL, including mode=asset when a trusted snapshot is archived. Historical legacy uploads may return the source URL. URL presence does not prove preparation readiness or promise long-term retention." }, "oss_url": { "type": "string", "format": "uri", "description": "Managed URL when storage is available. An enabled three-layer compatibility upload can archive a trusted snapshot in mode=asset as well as oss/both. Storage ready confirms a verified copy at the query time; retention, URL lifetime, and availability follow the separate storage service contract." }, "reference": { "type": "string", "examples": [ "Asset://asset_xxx" ], "description": "Asset reference for generation requests when supported." }, "asset_ref": { "type": "string", "examples": [ "Asset://asset_xxx" ], "description": "Asset reference, same meaning as reference." }, "content_type": { "type": "string", "examples": [ "image/png" ], "description": "MIME type." }, "size": { "type": "integer", "description": "File size in bytes." }, "duration": { "type": "number", "description": "Audio or video duration in seconds." }, "status": { "type": "string", "enum": [ "created", "syncing", "ready", "failed", "disabled" ], "description": "MoonApiX customer asset lifecycle. For a newly created V2 asset, ready means its stable MoonApiX identity and immutable content baseline are established; it does not mean a managed copy exists or preparation for a target model has succeeded. Historical records retain their previous status meaning." }, "sync_status": { "type": "string", "enum": [ "created", "syncing", "not_started", "processing", "ready", "not_required", "failed", "unknown" ], "description": "Legacy preparation alias. In the current MoonApiX asset API release, the enabled three-layer compatibility response uses the same explicit model/configuration scope as preparation.status; unknown means current readiness of a historical reference is unconfirmed and generation_ready is false. It is omitted without that scope in the transition and in explicit v2." }, "preparation_status": { "type": "string", "enum": [ "created", "syncing", "not_started", "processing", "ready", "not_required", "failed", "unknown", "disabled" ], "description": "Legacy preparation alias. In the current MoonApiX asset API release, the enabled three-layer compatibility response refers to the same scope as preparation.status; unknown means current readiness of a historical reference is unconfirmed and generation_ready is false. Explicit v2 uses only the nested preparation object." }, "generation_ready": { "type": "boolean", "description": "Legacy alias for preparation.generation_ready in the same target-model and calling scope. true means at least one currently permitted path can reference the asset without additional preparation; it does not guarantee immediate generation or change normal scheduling. For multiple assets, one path must satisfy all of them." }, "storage": { "$ref": "#/components/schemas/AssetStorage" }, "preparation": { "$ref": "#/components/schemas/AssetPreparation" }, "visibility": { "type": "string", "examples": [ "private" ], "description": "Asset visibility." }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "updated_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "request_id": { "type": "string", "description": "MoonApiX request ID." }, "trace_id": { "type": "string", "description": "MoonApiX trace ID for troubleshooting." }, "review_status": { "type": "string", "enum": [ "succeeded", "pending", "failed", "unknown" ], "description": "Review evidence, independently of preparation. unknown means no review evidence is available and does not itself deny an explicitly ready preparation. Historical review aliases are not proof that preparation has completed." }, "review_passed": { "type": "boolean", "description": "Legacy review alias: true only for review_status=succeeded. With review_status=unknown, false expresses missing review evidence rather than a review rejection, and does not itself deny explicit preparation readiness." }, "sync_error": { "type": "string", "description": "Asset preparation or synchronization failure reason. Usually present when preparation_status is failed." } }, "required": [ "object", "status" ], "anyOf": [ { "required": [ "id" ] }, { "required": [ "asset_id" ] } ], "example": { "id": "asset_xxx", "asset_id": "asset_xxx", "object": "asset", "type": "image", "asset_type": "image", "group_id": "group_xxx", "domain": "media", "name": "reference.png", "description": "", "source_url": "https://example.com/reference.png", "url": "https://example.com/reference.png", "oss_url": "", "reference": "Asset://asset_xxx", "asset_ref": "Asset://asset_xxx", "content_type": "image/png", "size": 245678, "duration": 0, "status": "ready", "sync_status": "ready", "preparation_status": "ready", "generation_ready": true, "visibility": "private", "created_at": 1710000000, "updated_at": 1710000000, "request_id": "2026060301010100000000000000000000", "trace_id": "2026060301010100000000000000000000", "review_status": "succeeded", "review_passed": true } }, "PaginatedAssets": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "count": { "type": "integer", "minimum": 0, "description": "Number of assets returned in this page.", "examples": [ 1 ] }, "total": { "type": "integer", "minimum": 0, "examples": [ 1 ] }, "data": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/AssetV2" } ] } }, "request_id": { "type": "string" }, "trace_id": { "type": "string" } }, "required": [ "object", "data", "count", "total" ] }, "DigitalHumanAvatar": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "asset_avatar_xxx" ] }, "avatar_asset_id": { "type": "string", "examples": [ "asset_avatar_xxx" ] }, "name": { "type": "string" }, "status": { "type": "string", "examples": [ "succeeded" ] }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds." } }, "required": [ "id" ] }, "DigitalHumanVoice": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "asset_voice_xxx" ] }, "voice_asset_id": { "type": "string", "examples": [ "asset_voice_xxx" ] }, "voice_id": { "type": "integer", "examples": [ 6339 ] }, "name": { "type": "string" }, "language": { "type": "string" }, "status": { "type": "string", "examples": [ "succeeded" ] } } }, "DigitalHumanTask": { "type": "object", "properties": { "task_id": { "type": "string", "examples": [ "task_xxx" ] }, "action": { "type": "string", "examples": [ "digital-human-audio" ] }, "model": { "type": "string", "examples": [ "digital-human-audio-v6" ] }, "status": { "type": "string", "enum": [ "SUBMITTED", "QUEUED", "IN_PROGRESS", "SUCCESS", "FAILURE", "CANCELED" ], "examples": [ "SUCCESS" ] }, "fail_reason": { "type": "string" }, "progress": { "type": "string", "examples": [ "100%" ] }, "result_url": { "type": "string", "format": "uri", "description": "MoonApiX-controlled result URL. Preserve the complete returned URL, including signed query parameters." }, "data": { "$ref": "#/components/schemas/DigitalHumanTaskData" } }, "required": [ "task_id", "status" ] }, "MusicTaskResponse": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "success" ] }, "message": { "type": "string", "examples": [ "success" ] }, "data": { "oneOf": [ { "type": "string", "examples": [ "task_xxx" ] }, { "$ref": "#/components/schemas/SunoTask" }, { "type": "array", "items": { "$ref": "#/components/schemas/SunoTask" } } ] } }, "required": [ "code", "data" ] }, "AudioSpeechRequest": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "tts-1" ] }, "input": { "type": "string" }, "voice": { "type": "string", "examples": [ "alloy" ] }, "response_format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac" ], "default": "mp3" }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4, "default": 1 } }, "required": [ "model", "input", "voice" ] }, "EmbeddingRequest": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "moonapix-embedding" ] }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "model", "input" ] }, "EmbeddingResponse": { "type": "object", "properties": { "object": { "type": "string", "examples": [ "list" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "examples": [ "embedding" ] }, "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "integer" } } } }, "model": { "type": "string" }, "usage": { "$ref": "#/components/schemas/EmbeddingUsage" } }, "required": [ "data" ] }, "GenericJsonResponse": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "success" ] }, "message": { "type": "string", "examples": [ "success" ] }, "data": { "oneOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "WebSearchRequest": { "type": "object", "properties": { "query": { "type": "string" }, "area": { "type": "string", "enum": [ "global", "cn" ], "default": "global" }, "freshness": { "type": "string", "enum": [ "Day", "Week", "Month", "Year" ] }, "includeImages": { "type": "boolean", "default": false }, "page": { "type": "integer", "minimum": 1, "default": 1 }, "count": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "format": { "type": "string", "enum": [ "json", "markdown", "md", "text", "txt" ], "default": "json" } }, "required": [ "query" ] }, "WebReaderRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "format": { "type": "string", "enum": [ "markdown", "md", "text", "txt" ], "default": "md" }, "liteMode": { "type": "boolean", "default": false }, "includeImages": { "type": "boolean", "default": true }, "onlyCSSSelectors": { "type": "array", "items": { "type": "string" } }, "waitForCSSSelectors": { "type": "array", "items": { "type": "string" } } }, "required": [ "url" ] }, "GeminiGenerateContentRequest": { "type": "object", "properties": { "contents": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "parts" ] } }, "generationConfig": { "type": "object", "additionalProperties": true }, "systemInstruction": { "type": "object", "additionalProperties": true } }, "required": [ "contents" ] }, "MusicSubmitRequest": { "type": "object", "properties": { "model": { "type": "string" }, "prompt": { "type": "string" }, "task_id": { "type": "string" }, "audioUrl": { "type": "string", "format": "uri" }, "sourceAudioUrl": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "tags": { "type": "string" }, "mv": { "type": "string" }, "make_instrumental": { "type": "boolean" }, "custom_mode": { "type": "boolean" }, "continue_at": { "type": "number" }, "instrumental": { "type": "boolean" }, "callBackUrl": { "type": "string", "format": "uri" }, "callback_url": { "type": "string", "format": "uri" } } }, "ImageEditRequest": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" }, "mask": { "type": "string", "format": "binary" }, "model": { "type": "string", "examples": [ "gpt-image-2-pro" ], "description": "Image model name, for example gpt-image-2-pro or gpt-image-2-vip." }, "prompt": { "type": "string", "description": "Edit instruction. Describe what to keep, what to change, and the target visual result." }, "n": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 }, "size": { "type": "string", "examples": [ "1024x1024" ], "description": "Output size. gpt-image-2-pro and gpt-image-2-vip use the same pixel-size calling rules, such as 1024x1024, 2048x2048, 3840x2160, or another supported 16-multiple custom size." } }, "required": [ "image", "model", "prompt" ] }, "ImageVariationRequest": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" }, "model": { "type": "string", "examples": [ "gpt-image-2" ] }, "n": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 }, "size": { "type": "string", "examples": [ "1024x1024" ] } }, "required": [ "image", "model" ] }, "IdeogramRequest": { "type": "object", "properties": { "prompt": { "type": "string" }, "image": { "type": "string", "format": "uri" }, "image_url": { "type": "string", "format": "uri" }, "aspect_ratio": { "type": "string", "examples": [ "1:1" ] }, "rendering_speed": { "type": "string" }, "style_type": { "type": "string" } }, "additionalProperties": true }, "MidjourneySubmitRequest": { "type": "object", "properties": { "prompt": { "type": "string" }, "base64Array": { "type": "array", "items": { "type": "string" } }, "notifyHook": { "type": "string", "format": "uri" }, "state": { "type": "string" } }, "additionalProperties": true }, "MidjourneyTaskResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "description": { "type": "string" }, "result": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "id": { "type": "string" }, "action": { "type": "string" }, "status": { "type": "string", "examples": [ "SUCCESS" ] }, "prompt": { "type": "string" }, "promptEn": { "type": "string" }, "submitTime": { "type": "string" }, "startTime": { "type": "string" }, "finishTime": { "type": "string" }, "imageUrl": { "type": "string", "format": "uri" }, "imageUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "progress": { "type": "string" }, "failReason": { "type": "string" }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/MidjourneyButton" } }, "state": { "type": "string" }, "properties": { "type": "object", "properties": { "finalPrompt": { "type": "string" }, "finalZhPrompt": { "type": "string" } } } }, "description": "Midjourney-compatible submit or task response." }, "VideoCreateRequest": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "moon-2.0-dj-fast", "seedance-2.0-sz", "seedance-2.0-sz-fast", "seedance-2.0-sz-mini", "seedance-2.5-sz", "seedance-2.5-cl", "doubao-seedance-2-0-260128", "doubao-seedance-2-0-fast-260128", "doubao-seedance-2-0-mini-260615", "seedance-2.0-cl-fast", "seedance-2.0-cl", "seedance-2.0-cl-mini", "seedance-2.0-cl-b-fast", "seedance-2.0-cl-b-mini", "seedance-2.0-gl", "seedance-2.0-gl-fast", "seedance-2.0-gl-mini", "moon-2.0-wc-720p", "moon-2.0-wc-b-720p-fast", "moon-2.0-wc-b-720p", "moon-2.0-wc-c-720p", "moon-2.0-wc-d-720p", "moon-2.0-wc-e-720p", "moon-2.0-wc-f-720p", "moon-2.0-gl-a-720p", "moon-2.0-gl-a-720p-fast", "moon-2.5-gl-a", "moon-2.0-ac-a-480p", "moon-2.0-ac-a-720p", "moon-2.0-ac-b-720p-fast", "moon-2.0-ac-c-720p", "moon-2.0-ac-d-720p", "moon-2.5-ac-a-480p", "moon-2.5-ac-a-720p", "moon-2.5-ac-b-720p", "moon-2.5-ac-c-720p", "moon-2.0-ld-a", "moon-2.0-ld-b", "moon-2.0-am-720p-fast", "moon-2.0-il-720p", "moon-2.0-me-a-720p", "moon-2.0-me-b-720p", "moon-2.0-me-a-fast", "grok-video-1.5", "grok-image-video", "seedance-2.0-sg-mini", "seedance-2.0-sg", "seedance-2.0-sg-fast", "seedance-2.5-sg", "seedance-2.0-nt", "seedance-2.0-nt-fast", "seedance-2.0-nt-mini", "seedance-2.5-nt", "seedance-2.0-sh", "seedance-2.0-sh-fast", "seedance-2.0-sh-mini", "seedance-2.5-sh", "doubao-seedance-2-5-260628" ] }, "prompt": { "type": "string", "description": "Video prompt. Describe subject, action, camera movement, scene, and style." }, "mode": { "type": "string", "description": "Optional generation mode when supported by the selected model." }, "image": { "type": "string", "description": "Source image URL. For models that support MoonApiX customer assets, this may also be Asset://asset_xxx." }, "image_url": { "type": "string", "description": "Source image URL." }, "images": { "type": "array", "description": "Compatibility image media array for covered models. New complex media integrations should prefer references[]. Items may be URL strings or objects like { url, role }. Submit only the image roles supported by the selected model, and do not mix incompatible first-frame, last-frame, or reference-image roles.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true, "properties": { "url": { "type": "string" }, "role": { "type": "string", "enum": [ "reference_image", "first_frame", "last_frame" ] }, "reference_voice": { "type": "string", "description": "Audio URL bound to this reference image when supported by the selected model." } } } ] } }, "input_reference": { "type": "string", "description": "Compatibility field for a single image reference URL or Asset:// reference. grok-video-1.5 commonly uses this field for single-image input." }, "input_reference_role": { "type": "string", "enum": [ "reference_image", "first_frame", "last_frame" ] }, "image_source_mode": { "type": "string", "enum": [ "asset", "direct_url" ], "description": "SG image intake mode. For SG requests containing images, omitting this field uses asset mode. asset prepares image inputs before submission and is recommended for person photos or other images that may be subject to privacy review. direct_url uses the supplied public image URLs directly and must be selected explicitly; person photos may be rejected by image privacy review. The selected mode applies to all images in the request." }, "avatar_asset_id": { "type": "string", "description": "An already-prepared SG avatar asset identifier for the current account. When this field is present and image_source_mode is omitted, asset mode is used." }, "avatar_asset_ids": { "type": "array", "description": "Already-prepared SG avatar asset identifiers for the current account. When this field is present and image_source_mode is omitted, asset mode is used.", "minItems": 1, "items": { "type": "string" } }, "first_frame_url": { "type": "string", "description": "First frame image URL or Asset:// reference." }, "last_frame_url": { "type": "string", "description": "Input last-frame reference image URL or Asset:// reference when supported by the selected model. This guides generation; it is not the generated result image returned as content.last_frame_url." }, "reference_image_url": { "type": "string", "description": "Single reference image URL or Asset:// reference." }, "reference_image_urls": { "type": "array", "description": "Reference image URLs or Asset:// references when supported by the selected model. grok-image-video supports up to 5 image references.", "items": { "type": "string" } }, "video": { "type": "string", "description": "Reference or source video URL." }, "video_url": { "type": "string", "description": "Reference or source video URL." }, "reference_video_url": { "type": "string", "description": "Single reference video URL or Asset:// reference when supported by the selected model." }, "reference_video_urls": { "type": "array", "description": "Reference video URLs or Asset:// references when supported by the selected model.", "items": { "type": "string" } }, "audio": { "type": "string", "description": "Reference audio URL." }, "audio_url": { "type": "string", "description": "Reference audio URL." }, "duration": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "examples": [ 5 ], "description": "Target video duration in seconds. Seedance SZ 2.0 models support 4-15 seconds, SZ 2.5 and seedance-2.5-cl support 4-30 seconds, moon-2.5-gl-a supports 4-30 seconds, and Moon-2 AC models follow the per-model duration matrix. -1 selects an integer duration automatically when supported. Do not send duration and frames together. NT models accept integer durations only: seedance-2.0-nt and seedance-2.0-nt-fast allow 4-15 seconds, seedance-2.0-nt-mini allows 4-15 seconds, and seedance-2.5-nt 4-30 seconds. NT does not support -1. SH 2.0 models accept integer durations 4-15 seconds or -1; SH 2.5 accepts 4-30 seconds or -1. Zero is invalid." }, "frames": { "type": "integer", "description": "Optional frame-count duration for models that support it. Mutually exclusive with duration; model capability rules apply. SH models do not support this field; sending it returns an explicit error." }, "seconds": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Video duration in seconds for models that use seconds. seedance-2.0-sz, seedance-2.0-sz-fast, and seedance-2.0-sz-mini support 4 through 15 seconds and the official smart-duration value -1; seedance-2.5-sz and seedance-2.5-cl support 4 through 30 seconds and -1. seedance-2.0-gl, seedance-2.0-gl-fast, and seedance-2.0-gl-mini support 4 through 15 seconds. moon-2.0-wc-720p supports 4 through 14 seconds; a client value of 15 is accepted for compatibility and generated as 14 seconds. This normalization does not apply to the WC-B models. moon-2.0-wc-f-720p supports 4 through 15 seconds. moon-2.0-gl-a-720p and moon-2.0-gl-a-720p-fast support 4 through 15 seconds. moon-2.5-gl-a supports 4 through 30 seconds. moon-2.0-ac-a-480p, moon-2.0-ac-b-720p-fast, moon-2.0-ac-c-720p, and moon-2.0-ac-d-720p support 15 seconds; moon-2.0-ac-a-720p supports 10 or 15 seconds. moon-2.5-ac-a-480p, moon-2.5-ac-a-720p, and moon-2.5-ac-b-720p support 4 through 30 seconds; moon-2.5-ac-c-720p supports 4 through 30 seconds except 5, 10, and 15. Use a string such as \"15\" for Grok video model compatibility. Grok video models currently support up to 15 seconds. For SH models this aliases duration with the same limits; conflicting aliases at the same level return an error." }, "aspect_ratio": { "type": "string", "examples": [ "16:9" ], "description": "MoonApiX aspect-ratio alias. For Seedance SZ and seedance-2.5-cl it is converted to the official ratio field. NT reference-image mode allows 16:9, 9:16, 1:1, 21:9, 4:3, and 3:4. For seedance-2.5-nt strict first/last-frame mode use adaptive or omit the ratio to preserve the first-frame aspect ratio; fixed ratios are rejected. Use reference_image for a fixed output ratio. SH supports adaptive, 21:9, 16:9, 9:16, 4:3, 3:4, and 1:1; SH 2.5 first/last-frame mode uses adaptive." }, "ratio": { "type": "string", "examples": [ "16:9" ], "description": "Official Seedance ratio field, for example 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive when supported." }, "size": { "type": "string", "description": "Size or resolution label depending on model. grok-video-1.5 supports 480P or 720P; grok-image-video supports 720P or 1080P; moon-2.5-gl-a supports 480P or 720P; Moon-2 AC models support the resolution listed in the model matrix. For SH models this aliases resolution; use a resolution label.", "examples": [ "1280x720" ] }, "resolution": { "type": "string", "examples": [ "720p" ], "description": "Video resolution label. SZ and seedance-2.5-cl models accept values according to the selected model capability, such as 480p, 720p, 1080p, or 4k. moon-2.5-gl-a supports 480P and 720P. Moon-2 AC models support 480P or 720P according to the selected model. NT standard models seedance-2.0-nt and seedance-2.5-nt support 720p and 1080p. NT Fast and Mini support 720p only. SH 2.0 standard supports 480P/720P/1080P/4K; SH Fast/Mini support 480P/720P; SH 2.5 supports 480P/720P/1080P." }, "generate_audio": { "type": "boolean", "default": true, "description": "Controls whether the generated video includes an audio track. true generates audio and false produces a silent video. Seedance SZ, CL, and GL models accept this field according to the selected model capability; the official default is true, but clients should pass it explicitly to avoid ambiguity. SH preserves explicit false; pass the intended value explicitly." }, "generateAudio": { "type": "boolean", "deprecated": true, "description": "Compatibility alias for generate_audio. New integrations should use generate_audio." }, "watermark": { "type": "boolean", "description": "Whether to add a watermark. The default is model-dependent; pass true or false explicitly when needed. SH models do not support this field; sending it returns an explicit error." }, "seed": { "type": "integer", "description": "Random seed. Omit or use -1 for a random result; a fixed seed only makes results similar, not frame-identical. SH models do not support this field; sending it returns an explicit error." }, "camera_fixed": { "type": "boolean", "description": "Whether to keep the camera fixed when supported by the selected model. SH models do not support this field; sending it returns an explicit error." }, "return_last_frame": { "type": "boolean", "default": false, "description": "Request the generated video's last-frame image. For seedance-2.5-cl, true has been verified in production: a successful task query may include content.last_frame_url in the default normalized response or compatible query response. No raw response mode is needed. Support depends on the selected model; this does not establish support for every model. SH models do not support this field; sending it returns an explicit error, including false or zero values." }, "omni_reference_task_type": { "type": "string", "enum": [ "auto", "reference", "edit", "extend" ], "default": "auto", "description": "Seedance 2.5 multimodal task type. edit requires a reference video, ratio=adaptive, and duration=-1. extend requires a reference video and ratio=adaptive. SH models do not support this field; sending it returns an explicit error, including false or zero values." }, "output_format": { "type": "string", "enum": [ "mp4", "mov" ], "default": "mp4", "description": "Seedance 2.5 output container. Use mov when a high-quality professional post-production workflow requires it. SH models do not support this field; sending it returns an explicit error, including false or zero values." }, "priority": { "type": "integer", "minimum": 0, "maximum": 9, "default": 0, "description": "Optional queue priority when enabled for the selected model and account. Explicit zero is preserved. SH models do not support this field; sending it returns an explicit error, including false or zero values." }, "draft": { "type": "boolean", "description": "Create a draft task when the selected model exposes draft generation. For SZ 2.5 drafts, use seedance-2.5-sz, draft=true and explicit resolution=480p. The final uses the same public model, explicit resolution=1080p and exactly one content[].draft_task item; omit draft or set false. SZ 2.5 draft_task.id accepts task_ or an eligible known cgt- draft ID; see the SZ model page. For SH 2.5 drafts, use draft=true and explicit resolution=480P. The draft-to-final workflow has not completed live validation. SH 2.0 models must omit draft and draft_task_id, even when draft would be false." }, "service_tier": { "type": "string", "default": "default", "description": "Requested service tier. Availability depends on the model and account. SH models do not support this field; sending it returns an explicit error." }, "execution_expires_after": { "type": "integer", "description": "Task execution expiration window in seconds. If omitted, the platform default is used. SH models do not support this field; sending it returns an explicit error, including false or zero values." }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Optional model tools. Use only when the selected model explicitly supports them. SH models do not support this field; sending it returns an explicit error." }, "safety_identifier": { "type": "string", "description": "Optional safety-policy identifier. Do not put credentials or sensitive personal data here. SH models do not support this field; sending it returns an explicit error, including false or zero values." }, "web_search": { "type": "boolean" }, "content": { "oneOf": [ { "$ref": "#/components/schemas/VideoContentItem" }, { "type": "array", "items": { "$ref": "#/components/schemas/VideoContentItem" } } ], "description": "OpenAI-compatible multimedia content items for covered or compatible models. For new MoonApiX complex media integrations, prefer references[] unless the model page explicitly recommends content[]. Image, video, and audio content items should include role. Common roles include reference_image, first_frame, last_frame, reference_video, and reference_audio. For compatibility with historical requests, media content without role is treated by media type as reference_image, reference_video, or reference_audio. Use an explicit role when you need first frame, last frame, reference-image audio binding, or another specific purpose. CL-B official-shaped mixed-media requests should also include a unique alias on every media item. seedance-2.5-cl accepts the same content item types when using its compatible request shape. Only seedance-2.5-sz final generation requires an array containing exactly one draft_task item. Its single id field uses task_ or an eligible cgt-; choose one. The ID must identify one known current-user draft with the same model and execution configuration, successful 480p output, no deletion, a seven-day lifetime and trusted original billing facts. Unknown or ambiguous IDs are rejected. Use the same model and explicit 1080p; do not resend prompt, media, duration, ratio, seed, generate_audio, camera_fixed or omni_reference_task_type. Draft and final are billed independently; the final inherits the original draft inputs' video-input category and returns a task_ ID." }, "callback_url": { "type": "string", "format": "uri", "description": "Completion callback when the selected model supports it. SH accepts callback_url only on POST /api/v3/contents/generations/tasks. MoonApiX delivers the callback; delivery has not completed live validation. SH requests on /v1/videos or /v1/video/generations reject callback_url. Use polling in the verified workflow." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional model parameters. You may place content, duration, seconds, resolution, or model-specific options here when a model requires them. SH generation fields use top-level > input > metadata precedence. Conflicting aliases at the same level return an error; explicit false is preserved. Ordinary business metadata is separate from generation parameters." }, "video_config": { "type": "object", "additionalProperties": true, "properties": { "aspect_ratio": { "type": "string", "examples": [ "16:9" ] }, "resolution_name": { "type": "string", "examples": [ "720p" ] }, "video_length": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Grok Imagine 1.0 video duration, commonly 6, 10, or 15 seconds." }, "resolution": { "type": "string", "description": "Grok Imagine compatibility resolution field, for example SD or HD.", "examples": [ "HD" ] } } }, "reference_images": { "type": "array", "description": "Grok Imagine compatibility field. Public reference image URLs for image-to-video models.", "items": { "type": "string" } }, "reference_voice": { "type": "string", "description": "Audio URL bound to a reference image when supported by the selected model." }, "videos": { "type": "array", "description": "Compatibility video media array for covered models when supported by the selected model. New complex media integrations should prefer references[]. Items may be URL strings or objects like { url, role: \"reference_video\" }.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true, "properties": { "url": { "type": "string" }, "role": { "type": "string", "enum": [ "reference_video" ] } } } ] } }, "audios": { "type": "array", "description": "Compatibility audio media array for covered models that support independent audio references, such as seedance-2.0-kz. New complex media integrations should prefer references[] when the selected model supports it. Audio references must be used together with image or video references, and audio-only requests may be rejected.", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true, "properties": { "url": { "type": "string" }, "role": { "type": "string", "enum": [ "reference_audio" ] } } } ] } }, "references": { "type": "array", "description": "Recommended MoonApiX multimedia reference array for new complex media integrations. Use media_type to identify image, video, audio, or music; role to describe usage; url for the media URL; and alias for prompt-addressable names such as @hero. Supported media types and roles depend on the selected model. Audio references must be used together with image or video references, and audio-only requests may be rejected. The seedance-2.0-sz, seedance-2.0-sz-fast, and seedance-2.0-sz-mini models support up to 9 images, 3 videos, and 3 audios with no more than 15 references total; seedance-2.5-sz and seedance-2.5-cl support up to 30 images, 10 videos, and 10 audios with no more than 50 references total. Video reference is supported by all four SZ models and seedance-2.5-cl, and remains subject to content safety review. seedance-2.0-gl, seedance-2.0-gl-fast, and seedance-2.0-gl-mini support up to 9 images, 3 videos, and 3 audios with no more than 15 references total; person references are supported but remain subject to content safety review. moon-2.0-dj-fast supports image references only, up to 9 images; reference images do not have to be face-only images and can describe people, clothing, products, scenes, composition, or visual style. moon-2.0-wc-720p, moon-2.0-wc-b-720p, moon-2.0-wc-b-720p-fast, and moon-2.0-wc-f-720p support people and references[] with up to 12 reference files total; within that total, use up to 9 images, 3 videos, and 3 audios. moon-2.0-wc-f-720p also supports text-only requests, and audio requires at least one image; a video does not satisfy that image requirement. moon-2.0-wc-720p supports text-only requests, while moon-2.0-wc-b-720p and moon-2.0-wc-b-720p-fast require reference media and do not support text-only requests. moon-2.0-wc-f-720p supports 4 through 15 seconds. moon-2.0-wc-720p supports 4 through 14 seconds; 15 is accepted for compatibility and generated as 14 seconds. moon-2.0-gl-a-720p and moon-2.0-gl-a-720p-fast support text-only requests or up to 4 images, 3 videos, and 1 audio, with no more than 8 references total; audio requires an image or video, and person references do not have to be face-only images. moon-2.0-ld-a and moon-2.0-ld-b have the same capabilities and support 720P tasks from 5 through 15 seconds with up to 9 images, 3 videos, and 3 audios, with no more than 15 reference files total; person references do not have to be face-only images. moon-2.0-am-720p-fast supports references[] for 720P fast tasks with image, video, and audio public URLs; audio references should be used together with image or video references. moon-2.0-me-a-720p and moon-2.0-me-a-fast support 720P tasks from 5 through 15 seconds with up to 9 images and no video or audio references. moon-2.0-me-b-720p supports 720P tasks from 5 through 15 seconds with up to 9 images, 3 videos, and 3 audios, with no more than 15 references total; audio requires an image or video. For URL-based reference media, prefer direct public media URLs with real file extensions such as .png, .mp4, .wav, or .mp3, without login, cookies, extra authorization headers, one-time download pages, or complex anti-hotlinking requirements. For seedance-2.5-cl, a failed authenticated Asset:// resolution is returned as an error and is never silently converted to a public URL. NT examples use public image URLs. NT asset authentication and Asset:// calls have not completed public workflow validation; failed authenticated asset resolution returns an error without URL fallback. First/last frames cannot be combined with reference media, and a last frame requires a first frame. SH 2.0 models allow up to 9 images/3 videos/3 audios; audio requires visual media. SH 2.5 allows 30 images/10 videos/10 audios, 50 total, and independent audio. A last frame requires a first frame; first/last frames cannot be mixed with ordinary references. Image AIGC preparation has been validated; successful video AIGC preparation and video-reference generation remain unvalidated. Liveness verification is not offered.", "items": { "$ref": "#/components/schemas/VideoReferenceItem" }, "x-model-capabilities": { "seedance-2.0-sg-mini": "480P/720P; integer durations 4-15 seconds or -1 for automatic duration. Configured limits: 9 images, 3 videos, 3 audios, 15 total; audio requires visual input. Verified 4-second single-image and 2-image/1-audio/1-video reference workflows. Billing uses usage.completion_tokens with resolution and video-input tiers. See https://docs.moonapix.com/api/videos/seedance-2-0-sg for paired request examples and current limits.", "seedance-2.0-sg": "480P/720P/1080P/4K; integer durations 4-15 seconds or -1. Configured limits: 9 images, 3 videos, 3 audios, 15 total; audio requires visual input. Verified 4-second single-image and 2-image/1-audio/1-video reference workflows. Billing uses usage.completion_tokens with resolution and video-input tiers.", "seedance-2.0-sg-fast": "480P/720P; integer durations 4-15 seconds or -1. Configured limits: 9 images, 3 videos, 3 audios, 15 total; audio requires visual input. Verified 4-second single-image and 2-image/1-audio/1-video reference workflows. Billing uses usage.completion_tokens with resolution and video-input tiers.", "seedance-2.5-sg": "480P/720P/1080P; integer durations 4-30 seconds or -1. Configured limits: 30 images, 10 videos, 10 audios, 50 total; audio requires visual input. Verified 4-second single-image and 2-image/1-audio/1-video reference workflows. Configured maxima and other durations are not all verified. Billing uses usage.completion_tokens with resolution and video-input tiers. Check status and error before using result URLs; preserve returned media URL query parameters and never send the API key to external media hosts.", "moon-2.5-gl-a": "Supports up to 30 image references, 10 video references, and 10 audio references, with no more than 50 references total. Audio references require at least one image or video. Supported resolutions are 480P and 720P; supported durations are 4 through 30 seconds.", "seedance-2.5-cl": "Supports text-to-video, image/video/audio references, up to 30 images, 10 videos, and 10 audios with no more than 50 references total. Supports 480P, 720P, and 1080P with durations from 4 through 30 seconds. Assets must be prepared for this model and be ready before use; failed Asset:// resolution returns an error instead of falling back to a public URL.", "moon-2.0-ac-a-480p": "480P, 15 seconds; requires at least one image and supports up to 9 images, 3 videos, and 3 audios, with no more than 15 references total.", "moon-2.0-ac-a-720p": "720P, 10 or 15 seconds; supports up to 9 image references and does not support video or audio references.", "moon-2.0-ac-b-720p-fast": "720P, 15 seconds; supports up to 9 images, 3 videos, and 3 audios, with no more than 15 references total.", "moon-2.0-ac-c-720p": "720P, 15 seconds; supports up to 9 image references and does not support video or audio references.", "moon-2.0-ac-d-720p": "720P, 15 seconds; supports up to 9 image references and does not support video or audio references.", "moon-2.5-ac-a-480p": "480P, 4 through 30 seconds; supports text-only or up to 30 image references and does not support video or audio references.", "moon-2.5-ac-a-720p": "720P, 4 through 30 seconds; supports text-only or up to 30 image references and does not support video or audio references.", "moon-2.5-ac-b-720p": "720P, 4 through 30 seconds; supports up to 30 images, 10 videos, and 10 audios, with no more than 50 references total.", "moon-2.5-ac-c-720p": "720P, 4 through 30 seconds except 5, 10, and 15 seconds; supports up to 30 images, 10 videos, and 10 audios, with no more than 50 references total.", "seedance-2.0-nt": "720P and 1080P; integer durations 4-15 seconds. Verified example: one public person reference image, reference_image role, 4 seconds, 16:9, generate_audio=false. Use polling; callbacks, cancellation, remix, extension, and authenticated asset creation are outside the verified NT workflow. Billing is per million video tokens, settled using usage.total_tokens with a separate tier for video-reference input. Current prices are available in the console and pricing API.", "seedance-2.0-nt-fast": "720P only; integer durations 4-15 seconds. Verified example: one public person reference image, reference_image role, 4 seconds, 16:9, generate_audio=false. Use polling; callbacks, cancellation, remix, extension, and authenticated asset creation are outside the verified NT workflow. Billing is per million video tokens, settled using usage.total_tokens with a separate tier for video-reference input. Current prices are available in the console and pricing API.", "seedance-2.0-nt-mini": "720P only; integer durations 4-15 seconds. Verified example: one public person reference image, reference_image role, 4 seconds, 16:9, generate_audio=false. Use polling; callbacks, cancellation, remix, extension, and authenticated asset creation are outside the verified NT workflow. Billing is per million video tokens, settled using usage.total_tokens with a separate tier for video-reference input. Current prices are available in the console and pricing API.", "seedance-2.5-nt": "720P and 1080P; integer durations 4-30 seconds. Verified example: one public person reference image, reference_image role, 4 seconds, 16:9, generate_audio=false. Use polling; callbacks, cancellation, remix, extension, and authenticated asset creation are outside the verified NT workflow. Billing is per million video tokens, settled using usage.total_tokens with a separate tier for video-reference input. Current prices are available in the console and pricing API.", "seedance-2.0-sh": "480P/720P/1080P/4K; 4-15 seconds or -1; 9 images/3 videos/3 audios; audio requires visual media. Configured limits are not exhaustive live validation. Verified SH 2.5 example: 1080P, 4 seconds, 16:9, text-to-video with audio, through both creation formats. Image AIGC preparation reached ready; video AIGC success, reference-video generation, and draft-to-final are unvalidated. No liveness verification, cancellation or remix. Billing uses output tokens with resolution/video-input tiers; current amounts are in the console and pricing API. See https://docs.moonapix.com/en/api/videos/seedance-2-0-sh.", "seedance-2.0-sh-fast": "480P/720P; 4-15 seconds or -1; 9 images/3 videos/3 audios; audio requires visual media. Configured limits are not exhaustive live validation. Verified SH 2.5 example: 1080P, 4 seconds, 16:9, text-to-video with audio, through both creation formats. Image AIGC preparation reached ready; video AIGC success, reference-video generation, and draft-to-final are unvalidated. No liveness verification, cancellation or remix. Billing uses output tokens with resolution/video-input tiers; current amounts are in the console and pricing API. See https://docs.moonapix.com/en/api/videos/seedance-2-0-sh.", "seedance-2.0-sh-mini": "480P/720P; 4-15 seconds or -1; 9 images/3 videos/3 audios; audio requires visual media. Configured limits are not exhaustive live validation. Verified SH 2.5 example: 1080P, 4 seconds, 16:9, text-to-video with audio, through both creation formats. Image AIGC preparation reached ready; video AIGC success, reference-video generation, and draft-to-final are unvalidated. No liveness verification, cancellation or remix. Billing uses output tokens with resolution/video-input tiers; current amounts are in the console and pricing API. See https://docs.moonapix.com/en/api/videos/seedance-2-0-sh.", "seedance-2.5-sh": "480P/720P/1080P; 4-30 seconds or -1; 30 images/10 videos/10 audios, 50 total; independent audio supported. Configured limits are not exhaustive live validation. Verified SH 2.5 example: 1080P, 4 seconds, 16:9, text-to-video with audio, through both creation formats. Image AIGC preparation reached ready; video AIGC success, reference-video generation, and draft-to-final are unvalidated. No liveness verification, cancellation or remix. Billing uses output tokens with resolution/video-input tiers; current amounts are in the console and pricing API. See https://docs.moonapix.com/en/api/videos/seedance-2-0-sh." } }, "input": { "type": "object", "additionalProperties": true, "description": "Optional nested generation fields for models that support input. SH precedence is top-level > input > metadata; same-level conflicting aliases return an error. Use one reference representation per request." }, "draft_task_id": { "type": "string", "description": "For SH 2.5 final generation, the MoonApiX public ID of a successful eligible draft created within seven days. Send model, draft_task_id and explicit resolution=1080P; omit inherited prompt, references, duration, ratio and audio settings. Ownership and draft eligibility are checked. The live draft-to-final workflow remains unvalidated." }, "off_peak": { "type": "boolean", "description": "SH generation option. Explicit false is preserved. Availability and billing follow the selected model and current quote." }, "kwargs": { "type": "object", "additionalProperties": false, "description": "SH compatibility container for only generate_audio, draft, draft_task_id and off_peak. Prefer top-level fields. A field and kwargs.field at the same level must be identical. Source precedence is top-level > input > metadata. Model limits still apply, including no draft fields for SH 2.0.", "properties": { "generate_audio": { "$ref": "#/components/schemas/VideoCreateRequest/properties/generate_audio" }, "draft": { "$ref": "#/components/schemas/VideoCreateRequest/properties/draft" }, "draft_task_id": { "$ref": "#/components/schemas/VideoCreateRequest/properties/draft_task_id" }, "off_peak": { "$ref": "#/components/schemas/VideoCreateRequest/properties/off_peak" } } } }, "additionalProperties": true, "required": [ "model" ], "example": { "model": "moon-2.0-wc-720p", "prompt": "Let @robot wave naturally, keep the subject consistent, stable camera.", "duration": 14, "ratio": "16:9", "resolution": "720P", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/robot.png", "alias": "robot" } ] }, "description": "Video creation request. The selected model requires a prompt, supported content/media input, or a draft reference supported by that model. SZ 2.5 uses content[].draft_task.id; SH 2.5 uses top-level draft_task_id. Do not mix these shapes. Exact required fields, combinations and limits are validated per model; unsupported fields are not silently ignored." }, "AssetCreateMediaRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Existing public media URL. Recommended when your file is already reachable." }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Multiple existing public media URLs. Each URL creates one asset." }, "group_id": { "type": "string", "description": "Asset group ID. If omitted, the default group is used. A liveness verification result provides a private group ID; uploading media to that group creates the asset ID." }, "model": { "type": "string", "examples": [ "seedance-2.0-kz-fast", "doubao-seedance-2-0-260128" ], "description": "Target model name when creating an Asset:// reference." }, "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ], "description": "Asset type." }, "name": { "type": "string", "description": "Optional asset name." }, "description": { "type": "string", "description": "Optional asset description." }, "purpose": { "type": "string", "examples": [ "video_reference" ], "description": "Optional asset purpose." }, "mode": { "type": "string", "enum": [ "asset", "oss", "both" ], "description": "asset saves the source URL and performs free asset authentication/preparation for an Asset:// reference. oss creates a free MoonApiX OSS test URL. both creates both outputs for free. MoonApiX OSS is for testing only and has no long-term retention or availability guarantee; production clients must provide their own anonymously accessible public URL." } }, "additionalProperties": true, "example": { "model": "seedance-2.0-kz-fast", "mode": "asset", "type": "image", "group_id": "group_xxx", "url": "https://example.com/reference.png" } }, "TaskChainStep": { "type": "object", "properties": { "step": { "type": "string", "examples": [ "generation" ] }, "status": { "type": "string", "examples": [ "succeeded" ] }, "message": { "type": "string" }, "started_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "finished_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "asset_id": { "type": "string", "examples": [ "asset_xxx" ] }, "public_model": { "type": "string", "examples": [ "seedance-2.0-kz-fast" ] }, "trace_id": { "type": "string" }, "result_url_policy": { "type": "string", "enum": [ "pending", "direct_return", "transfer_to_moonapix_storage", "proxy", "proxy_data_uri", "proxy_missing_result_url", "skipped" ] }, "result_url": { "type": "string", "format": "uri", "description": "Customer-usable result URL. It may be an approved direct media URL or a MoonApiX-managed URL; preserve the complete returned URL, including signed query parameters." }, "metadata": { "$ref": "#/components/schemas/TaskChainMetadata" } } }, "ChatCompletionChoice": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string", "examples": [ "assistant" ] }, "content": { "type": "string" }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "function": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" } } } } } } }, "required": [ "role" ] }, "finish_reason": { "type": "string", "examples": [ "stop" ] } }, "required": [ "index", "message" ] }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } }, "required": [ "total_tokens" ] }, "ChatCompletionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "examples": [ "chat.completion" ] }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionChoice" } }, "usage": { "$ref": "#/components/schemas/Usage" } }, "required": [ "id", "object", "choices" ] }, "ImageResult": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Customer-usable output URL. It may be an approved direct media URL or a MoonApiX-managed URL; preserve the complete returned URL." }, "b64_json": { "type": "string" }, "revised_prompt": { "type": "string" }, "prompt": { "type": "string" }, "resolution": { "type": "string" }, "is_image_safe": { "type": "boolean" }, "seed": { "type": "integer" }, "style_type": { "type": "string" } }, "description": "One generated or returned image item." }, "ImageResponse": { "type": "object", "properties": { "created": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResult" } } }, "required": [ "data" ] }, "IdeogramResponse": { "allOf": [ { "$ref": "#/components/schemas/ImageResponse" } ] }, "IdeogramDescribeResponse": { "type": "object", "properties": { "created": { "type": "string" }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageResult" } } }, "required": [ "data" ] }, "MidjourneyButton": { "type": "object", "properties": { "label": { "type": "string" }, "customId": { "type": "string" }, "type": { "type": "string" }, "style": { "type": "string" } }, "required": [ "label", "customId" ] }, "MidjourneyTaskListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/MidjourneyTaskResponse" } }, "MidjourneyImageSeedResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "description": { "type": "string" }, "result": { "type": "string" } }, "required": [ "code", "result" ] }, "TaskOutputMetadata": { "type": "object", "properties": { "width": { "type": "integer", "description": "Media width in pixels." }, "height": { "type": "integer", "description": "Media height in pixels." }, "duration": { "type": "number", "description": "Media duration in seconds." }, "prompt": { "type": "string" }, "seed": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "model": { "type": "string" } } }, "TaskOutputItem": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "video" ], "enum": [ "image", "video", "audio", "file", "text" ] }, "url": { "type": "string", "format": "uri" }, "content_type": { "type": "string", "examples": [ "video/mp4" ] }, "filename": { "type": "string" }, "size": { "type": "integer", "description": "File size in bytes." }, "duration": { "type": "number", "description": "Media duration in seconds." }, "width": { "type": "integer", "description": "Media width in pixels." }, "height": { "type": "integer", "description": "Media height in pixels." }, "text": { "type": "string" }, "asset_id": { "type": "string", "examples": [ "asset_xxx" ] }, "metadata": { "$ref": "#/components/schemas/TaskOutputMetadata" } }, "required": [ "type" ] }, "DigitalHumanTaskData": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "success" ] }, "audio_url": { "type": "string", "format": "uri" }, "audio_duration": { "type": "integer", "description": "Audio duration in milliseconds." }, "output_video_url": { "type": "string", "format": "uri" }, "output_video_cover_url": { "type": "string", "format": "uri" }, "video_duration": { "type": "integer", "description": "Video duration in milliseconds." } } }, "DigitalHumanTaskSubmitResponse": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "success" ] }, "message": { "type": "string", "examples": [ "success" ] }, "data": { "type": "string", "examples": [ "task_xxx" ] } }, "required": [ "code", "data" ] }, "DigitalHumanTaskResponse": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "success" ] }, "message": { "type": "string", "examples": [ "success" ] }, "data": { "$ref": "#/components/schemas/DigitalHumanTask" } }, "required": [ "code", "data" ] }, "DigitalHumanTaskListResponse": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "success" ] }, "message": { "type": "string", "examples": [ "success" ] }, "data": { "type": "object", "properties": { "page": { "type": "integer", "examples": [ 1 ] }, "page_size": { "type": "integer", "examples": [ 10 ] }, "total": { "type": "integer", "examples": [ 0 ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DigitalHumanTask" } } }, "required": [ "items" ] } }, "required": [ "code", "data" ] }, "SunoMediaItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "audio", "image", "video", "wav", "midi" ], "examples": [ "audio" ] }, "index": { "type": "integer", "examples": [ 0 ] }, "url": { "type": "string", "format": "uri", "description": "MoonApiX media URL." }, "content_type": { "type": "string", "examples": [ "audio/mpeg" ] }, "size": { "type": "integer", "description": "File size in bytes.", "examples": [ 6439893 ] }, "expires_in": { "type": "integer", "description": "Remaining URL validity in seconds.", "examples": [ 604800 ] }, "title": { "type": "string", "examples": [ "Rainy Alley" ] }, "duration": { "type": "number", "description": "Audio or video duration in seconds.", "examples": [ 281.2 ] }, "suno_audio_id": { "type": "string", "description": "Audio ID for follow-up music operations." }, "filename": { "type": "string", "examples": [ "rainy-alley-1.mp3" ] } } }, "SunoTaskData": { "type": "object", "properties": { "task_id": { "type": "string" }, "action": { "type": "string" }, "status": { "type": "string" }, "audio_url": { "type": "string", "format": "uri" }, "image_url": { "type": "string", "format": "uri" }, "video_url": { "type": "string", "format": "uri" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/SunoMediaItem" } } } }, "SunoTask": { "type": "object", "properties": { "id": { "type": "integer" }, "task_id": { "type": "string", "examples": [ "task_xxx" ] }, "action": { "type": "string", "examples": [ "generate-music" ] }, "status": { "type": "string", "enum": [ "SUBMITTED", "QUEUED", "IN_PROGRESS", "SUCCESS", "FAILURE" ], "examples": [ "SUCCESS" ] }, "fail_reason": { "type": "string" }, "progress": { "type": "string", "examples": [ "100%" ] }, "result_url": { "type": "string", "format": "uri", "description": "First available media URL." }, "data": { "$ref": "#/components/schemas/SunoTaskData" } }, "required": [ "task_id", "status" ] }, "EmbeddingUsage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } }, "TaskChainMetadata": { "type": "object", "properties": { "model": { "type": "string" }, "asset_id": { "type": "string" }, "result_url": { "type": "string", "format": "uri", "description": "Customer-usable video result URL. It may be an approved direct media URL or a MoonApiX-managed URL. Preserve the complete returned URL, including signed query parameters." }, "result_url_policy": { "type": "string" }, "content_type": { "type": "string" }, "duration": { "type": "number" }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "VideoMediaURL": { "type": "object", "properties": { "url": { "type": "string", "description": "Media URL or Asset:// reference when supported by the selected model." }, "asset_id": { "type": "string", "description": "MoonApiX asset ID." }, "asset-id": { "type": "string", "description": "MoonApiX asset ID compatibility field." }, "asset_url": { "type": "string", "description": "Asset:// reference when supported by the selected model." } }, "additionalProperties": true }, "VideoContentItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "image_url", "video_url", "audio_url", "draft_task" ] }, "text": { "type": "string" }, "image_url": { "$ref": "#/components/schemas/VideoMediaURL" }, "video_url": { "$ref": "#/components/schemas/VideoMediaURL" }, "audio_url": { "$ref": "#/components/schemas/VideoMediaURL" }, "role": { "type": "string", "enum": [ "reference_image", "first_frame", "last_frame", "reference_video", "reference_audio" ] }, "asset_id": { "type": "string" }, "asset-id": { "type": "string" }, "asset_url": { "type": "string" }, "subject_type": { "type": "string" }, "reference_voice": { "type": "string", "description": "Audio URL bound to this reference image item." }, "draft_task": { "type": "object", "description": "Final-generation reference only for seedance-2.5-sz. The id accepts task_ or an eligible known cgt- draft ID. Use type=draft_task and a content array containing only this item; do not mix it with text or media items. The final continues to return a MoonApiX task_ public task ID.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "One string: a MoonApiX task_ public draft task ID or a cgt- draft ID. Choose one. The cgt- format is cgt-, 14 digits, a hyphen and 1 to 64 ASCII letters or digits. It must resolve to exactly one known current-user draft with the same public model and valid execution configuration, successful 480p output, no deletion, use within seven days of original creation, and trusted original billing facts. Unknown, ambiguous or mismatched IDs are rejected; arbitrary external tasks are not accepted. This compatibility does not apply to other APIs or models.", "example": "task_draft_example", "examples": [ "task_draft_example", "cgt-20261027000000-example" ] } }, "additionalProperties": false } }, "additionalProperties": true }, "VideoTaskContent": { "type": "object", "description": "Generated video result fields. Check task status and error before using these URLs.", "properties": { "video_url": { "type": "string", "format": "uri", "description": "Generated video URL when available. Preserve the complete returned URL, including query parameters, and download temporary media promptly." }, "last_frame_url": { "type": "string", "format": "uri", "description": "Optional generated last-frame image URL, separate from content.video_url and the input last_frame_url reference. The seedance-2.5-cl workflow with return_last_frame=true has been verified in production. This field may be omitted when not requested, not produced, or unavailable for safe public access. No raw response mode is needed. Identify the image format from the actual Content-Type; PNG is not guaranteed (a production result was JPEG). Preserve query parameters and download temporary URLs promptly." } } }, "OpenAIVideoResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "For normalized video task queries, the MoonApiX public task ID returned on creation.", "examples": [ "task_xxx" ] }, "task_id": { "type": "string", "description": "For normalized video task queries, the same MoonApiX public task ID as id.", "examples": [ "task_xxx" ] }, "object": { "type": "string", "examples": [ "video" ] }, "model": { "type": "string", "examples": [ "seedance-2.0-kz-fast" ] }, "status": { "type": "string", "enum": [ "pending", "submitted", "running", "succeeded", "failed", "cancelled", "queued", "in_progress", "completed" ], "description": "Optional top-level status. Some video responses may omit it; if missing, read data.status when present. SG responses use queued, in_progress, completed or failed; check status and error before using a result URL." }, "progress": { "type": "integer" }, "output_format": { "type": "string", "enum": [ "mp4", "mov" ], "description": "Actual output container when returned by the video task." }, "priority": { "type": "integer", "minimum": 0, "maximum": 9, "description": "Task execution priority when returned by the video task." }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "completed_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "expires_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "seconds": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "size": { "type": "string" }, "remixed_from_video_id": { "type": "string" }, "content": { "$ref": "#/components/schemas/VideoTaskContent" }, "result_url": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri", "description": "Customer-usable video result URL. It may be an approved direct media URL or a MoonApiX-managed URL. Preserve the complete returned URL, including signed query parameters." }, "video_url": { "type": "string", "format": "uri", "description": "Customer-usable video result URL. It may be an approved direct media URL or a MoonApiX-managed URL. Preserve the complete returned URL, including signed query parameters." }, "output": { "oneOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, { "type": "array", "items": { "$ref": "#/components/schemas/TaskOutputItem" } } ] }, "metadata": { "type": "object", "additionalProperties": true, "properties": { "request_id": { "type": "string" }, "trace_id": { "type": "string" }, "url": { "type": "string", "description": "Customer-usable result URL or content URL when available. It may be an approved direct media URL or a MoonApiX-managed URL." } } }, "error": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "data": { "type": "object", "description": "Model response payload. For seedance-2.0-kz tasks this may contain task_id, status, error, duration, usage, and video_url.", "additionalProperties": true, "properties": { "task_id": { "type": "string", "description": "Model task ID for troubleshooting." }, "status": { "type": "string", "examples": [ "running", "succeeded", "failed" ], "description": "Task status when top-level status is absent." }, "error": { "type": "string", "description": "Failure reason when status is failed." }, "duration": { "type": "number", "description": "Video duration in seconds." }, "video_url": { "type": "string", "format": "uri", "description": "Final video URL when available." }, "usage": { "type": "object", "additionalProperties": true, "description": "Usage information when available." } } }, "request_id": { "type": "string", "description": "MoonApiX request ID." }, "trace_id": { "type": "string", "description": "MoonApiX trace ID." }, "message": { "type": "string", "description": "Response message." }, "code": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Compatibility response code when present." }, "resolution": { "type": "string", "description": "Resolution label when returned by the task. SG normalizes valid labels to lowercase (480p, 720p, 1080p, 4k); supported resolutions depend on the selected model. This label does not verify the encoded pixel dimensions or indicate task success.", "examples": [ "1080p", "4k" ] }, "duration": { "type": "number", "description": "Duration in seconds when returned by the task; the encoded file duration may differ slightly.", "examples": [ 4 ] } }, "required": [ "id", "status" ] }, "RemoteCancelResult": { "type": "object", "description": "Best-effort cancellation result for an in-progress generation. MoonApiX cancellation and refund can succeed even when this extra stop attempt is unsupported.", "properties": { "attempted": { "type": "boolean", "description": "Whether MoonApiX attempted to stop the running generation." }, "supported": { "type": "boolean", "description": "Whether the selected model supports cancelling an in-progress task." }, "succeeded": { "type": "boolean", "description": "Whether the stop attempt succeeded." }, "error": { "type": "string", "description": "Cancel attempt error message when available." } }, "required": [ "attempted", "supported", "succeeded" ] }, "VideoCancelResponse": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "task_01HX..." ] }, "object": { "type": "string", "examples": [ "video" ] }, "status": { "type": "string", "enum": [ "cancelled", "failed" ], "examples": [ "cancelled" ] }, "cancelled": { "type": "boolean", "description": "Whether the task is considered cancelled by MoonApiX." }, "refund_requested": { "type": "boolean", "description": "Whether MoonApiX requested a refund of pre-consumed quota." }, "remote_cancel": { "$ref": "#/components/schemas/RemoteCancelResult" }, "trace_id": { "type": "string", "description": "MoonApiX request trace ID." }, "request_id": { "type": "string", "description": "MoonApiX request ID. Usually the same as trace_id." }, "task_chain": { "type": "array", "description": "Task chain summary including cancel, quota settlement, and optional remote_cancel steps.", "items": { "$ref": "#/components/schemas/TaskChainStep" } } }, "required": [ "id", "status", "cancelled", "refund_requested" ], "example": { "id": "task_01HX...", "object": "video", "status": "cancelled", "cancelled": true, "refund_requested": true, "remote_cancel": { "attempted": true, "supported": false, "succeeded": false, "error": "" }, "trace_id": "2026060301010100000000000000000000", "request_id": "2026060301010100000000000000000000", "task_chain": [ { "step": "cancel", "status": "succeeded" }, { "step": "billing", "status": "refunded" }, { "step": "remote_cancel", "status": "skipped" } ] } }, "AssetGroup": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "group_xxx" ] }, "object": { "type": "string", "examples": [ "asset_group" ] }, "group_id": { "type": "string", "examples": [ "group_xxx" ] }, "name": { "type": "string", "examples": [ "project-a" ] }, "description": { "type": "string", "examples": [ "Project A materials" ] }, "domain": { "type": "string", "examples": [ "media" ] }, "group_type": { "type": "string", "enum": [ "default", "custom", "system" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "created_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "updated_at": { "type": "integer", "description": "Unix timestamp in seconds." }, "visibility": { "type": "string", "examples": [ "private" ], "description": "Group visibility." }, "request_id": { "type": "string", "description": "MoonApiX request ID." }, "trace_id": { "type": "string", "description": "MoonApiX trace ID." } }, "required": [ "id", "object", "group_id", "name", "status" ], "example": { "id": "group_xxx", "object": "asset_group", "group_id": "group_xxx", "name": "project-a", "description": "Project A materials", "domain": "media", "group_type": "custom", "status": "enabled", "created_at": 1710000000, "updated_at": 1710000000, "visibility": "private", "request_id": "2026060301010100000000000000000000", "trace_id": "2026060301010100000000000000000000" } }, "PaginatedAssetGroups": { "type": "object", "properties": { "object": { "type": "string", "examples": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetGroup" } }, "count": { "type": "integer", "examples": [ 1 ] }, "total": { "type": "integer", "examples": [ 1 ] }, "trace_id": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "object", "data" ] }, "VideoReferenceItem": { "type": "object", "additionalProperties": true, "properties": { "media_type": { "type": "string", "enum": [ "image", "video", "audio", "music" ], "description": "Media type for a MoonApiX reference item." }, "role": { "type": "string", "enum": [ "first_frame", "last_frame", "reference_image", "reference_video", "reference_audio", "background_music", "voice_reference", "style_reference", "character_reference" ], "description": "How the model should use this reference. Supported roles depend on the selected model." }, "url": { "type": "string", "description": "Customer-owned public URL, MoonApiX OSS test URL, or Asset:// reference when supported by the selected model. MoonApiX OSS test URLs have no long-term availability guarantee." }, "alias": { "type": "string", "description": "Optional user-facing alias without the @ prefix. Aliases should be unique within one request. When omitted, aliases are assigned sequentially per media type as 图片1, 图片2, 视频1, 音频1, and so on. Prompts may use @图片1 or the compatibility form @图片 1; text may immediately follow the numeric index, for example @图片1保持人物外观. The same rule applies to 视频N and 音频N. Custom aliases must be separated from following prompt text by whitespace or punctuation. An unknown alias returns invalid_reference_alias; one alias bound to multiple different references returns duplicate_reference_alias. Alias binding identifies prompt references but does not guarantee independent identity fidelity for multiple people." }, "asset_id": { "type": "string", "description": "Optional MoonApiX asset ID." }, "asset_ref": { "type": "string", "description": "Optional MoonApiX asset reference, such as Asset://asset_xxx." } }, "required": [ "media_type", "role", "url" ], "example": { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference.png", "alias": "hero" } }, "ImageAsyncGenerationRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Image model name, for example gpt-image-2, gpt-image-2-pro, or gpt-image-2-vip.", "examples": [ "gpt-image-2" ] }, "prompt": { "type": "string", "description": "Image description. Include subject, scene, style, composition, aspect ratio, and intended use when relevant." }, "size": { "type": "string", "description": "Output size, for example 1024x1024.", "examples": [ "1024x1024" ] }, "n": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 } } }, "ImageJSONEditRequest": { "type": "object", "description": "Optional synchronous JSON image edit request supported by some API key groups. Availability, accepted image count, and limits depend on the current API key group and selected model. Use multipart/form-data when JSON URL input is unavailable for the current group.", "required": [ "model", "prompt", "image" ], "properties": { "model": { "type": "string", "description": "Image model name available to the current API key group.", "examples": [ "gpt-image-2" ] }, "prompt": { "type": "string", "description": "Edit instruction. Describe what to keep, what to change, and the target result." }, "image": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } } ], "description": "One public image URL, or an array of public image URLs when multiple images are supported by the current API key group and model." }, "size": { "type": "string", "description": "Output size supported by the selected model.", "examples": [ "1024x1024" ] }, "quality": { "type": "string", "description": "Optional output quality supported by the selected model." }, "n": { "type": "integer", "minimum": 1, "default": 1 } } }, "ImageAsyncEditRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "description": "Image model name available to the current API key group, for example gpt-image-2, gpt-image-2-pro, gpt-image-2-vip, or gemini-3-pro-image-preview.", "examples": [ "gpt-image-2", "gemini-3-pro-image-preview" ] }, "prompt": { "type": "string", "description": "Edit instruction. Describe what to keep, what to change, and the target result." }, "image": { "oneOf": [ { "type": "string" }, { "type": "array", "minItems": 1, "items": { "type": "string" } } ], "description": "MoonApiX canonical async edit input. Use one public image URL or Base64 Data URL string for a single reference, or an array of strings for multiple references." }, "image_url": { "type": "string", "description": "Compatibility alias for a single input image URL. New integrations should use image." }, "mask": { "type": "string", "description": "Optional mask URL or Base64 content when supported by the selected model." }, "size": { "type": "string", "description": "Output size or aspect-ratio label supported by the selected model, for example 1024x1024 or 16:9.", "examples": [ "1024x1024", "16:9" ] }, "resolution": { "type": "string", "description": "Optional resolution preset supported by the selected model, for example 1K, 2K, or 4K.", "examples": [ "4K" ] }, "quality": { "type": "string", "description": "Optional output quality preset. Omit this field to use the selected model's default behavior. Explicit values depend on the selected model." }, "n": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 } } }, "ImageTaskResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "MoonApiX public image task ID.", "examples": [ "task_xxx" ] }, "object": { "type": "string", "enum": [ "image.generation", "image.edit" ], "description": "Image task object type." }, "created": { "type": "integer", "description": "Unix timestamp when the task was created." }, "status": { "type": "string", "enum": [ "submitted", "queued", "running", "succeeded", "failed" ], "description": "Public image task status." }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Task progress percentage." }, "model": { "type": "string", "description": "Requested model name." }, "request_id": { "type": "string", "description": "MoonApiX request ID for support and debugging." }, "data": { "type": "array", "description": "Present when the task succeeded. Async image tasks return URLs.", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Generated image URL." } } } }, "error": { "type": "object", "description": "Present when the task failed.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "AssetStorage": { "type": "object", "additionalProperties": false, "description": "Independent managed-storage state. ready confirms that a verified, accessible managed copy exists at query time; it does not prove model preparation succeeded or promise permanent retention.", "properties": { "status": { "type": "string", "enum": [ "not_started", "processing", "ready", "failed", "unknown" ] }, "error": { "$ref": "#/components/schemas/AssetOperationError" } }, "required": [ "status" ] }, "AssetPreparation": { "type": "object", "additionalProperties": false, "description": "Returned only when a public target model and current calling scope are explicitly specified. Clients should normally require status=ready or not_required together with generation_ready=true. This result does not change normal scheduling and is revalidated at generation time. review_status=unknown means no independent review evidence is available; it is neither approval nor rejection.", "properties": { "model": { "type": "string", "description": "Public target model to which this readiness result applies.", "examples": [ "seedance-2.5-cl" ] }, "status": { "type": "string", "enum": [ "not_started", "processing", "ready", "not_required", "failed", "unknown" ], "description": "unknown means a historical reference may exist but its current readiness for this model and calling scope is unconfirmed; generation_ready is false. It does not establish preparation failure or asset deletion and is separate from review_status=unknown. GET does not establish new readiness evidence." }, "generation_ready": { "type": "boolean", "description": "At least one currently permitted path can reference the asset without additional preparation; for multiple assets, the same path must satisfy every asset. This does not guarantee immediate generation or change normal scheduling. The selected route and binding are revalidated at generation time." }, "review_status": { "type": "string", "enum": [ "unknown", "succeeded", "pending", "failed" ], "description": "Independent review evidence. unknown means no evidence is available; it is neither approval nor rejection and does not by itself invalidate a confirmed preparation result." }, "error": { "$ref": "#/components/schemas/AssetPreparationError" } }, "required": [ "model", "status", "generation_ready", "review_status" ] }, "AssetOperationError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "AssetPreparationError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, "AssetV2": { "type": "object", "additionalProperties": false, "x-release-status": "active", "description": "Active three-layer projection. For a newly created V2 asset, status=ready means a stable MoonApiX identity and verified immutable content exist; storage and preparation are computed independently. Historical records retain their previous lifecycle meaning. preparation is returned only when model is explicitly supplied in an asset detail query. asset_id and asset_ref identify the MoonApiX asset and are not asset IDs from another service.", "properties": { "object": { "type": "string", "const": "asset" }, "asset_id": { "type": "string", "examples": [ "asset_xxx" ] }, "asset_ref": { "type": "string", "examples": [ "Asset://asset_xxx" ] }, "group_id": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "created", "syncing", "ready", "failed", "disabled" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "storage": { "$ref": "#/components/schemas/AssetStorage" }, "preparation": { "$ref": "#/components/schemas/AssetPreparation" }, "request_id": { "type": "string" }, "trace_id": { "type": "string" }, "deleted": { "type": "boolean", "const": true, "description": "Returned only after successful DELETE; the asset is soft-deleted with status=disabled." } }, "required": [ "object", "asset_id", "status", "storage" ], "example": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "type": "image", "status": "ready", "storage": { "status": "ready" }, "preparation": { "model": "seedance-2.5-cl", "status": "ready", "generation_ready": true, "review_status": "unknown" } } }, "AssetStorageRequest": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false, "description": "Request intent to archive the verified content after identity creation. This is not a storage fact and is not echoed as a permanent response field." } }, "required": [ "enabled" ] }, "AssetCreateV2JSONRequest": { "type": "object", "additionalProperties": false, "x-release-status": "active", "description": "Active in the current MoonApiX asset API release. Selected only by MoonApiX-Asset-Contract: v2. One URL creates an immutable content snapshot and identity; it does not perform model preparation. model, mode, urls, purpose, subject_type, and role are rejected.", "properties": { "url": { "type": "string", "format": "uri", "description": "One accessible HTTP or HTTPS media source. MoonApiX verifies the bytes before assigning the identity." }, "type": { "type": "string", "enum": [ "image", "audio", "video" ], "default": "image" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 4096 }, "group_id": { "type": "string" }, "storage": { "$ref": "#/components/schemas/AssetStorageRequest" } }, "required": [ "url" ] }, "AssetCreateV2MultipartRequest": { "type": "object", "additionalProperties": false, "x-release-status": "active", "description": "Active in the current MoonApiX asset API release. Selected only by MoonApiX-Asset-Contract: v2. Exactly one file; repeated fields and legacy model/mode/purpose/role/subject_type fields are rejected. URL and batch inputs are not accepted in multipart V2 creation.", "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string", "enum": [ "image", "audio", "video" ], "default": "image" }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 4096 }, "group_id": { "type": "string" }, "storage": { "type": "string", "description": "JSON form field with exactly one boolean enabled property. It requests archive execution, not proof of storage success.", "example": "{\"enabled\":true}" } }, "required": [ "file" ] }, "AssetArchiveJSONRequest": { "type": "object", "additionalProperties": false, "description": "Omit the body or send {} to reuse an available recorded source. Otherwise send one url whose bytes must match the immutable content baseline. The same URL alone is not evidence of equal content.", "properties": { "url": { "type": "string", "format": "uri" } } }, "AssetArchiveMultipartRequest": { "type": "object", "additionalProperties": false, "properties": { "file": { "type": "string", "format": "binary", "description": "Exactly one file matching the existing immutable content baseline. Other form fields and repeated files are rejected." } }, "required": [ "file" ] }, "AssetPrepareRequest": { "type": "object", "description": "Prepare or resume only the normally selected execution path. Omit operation to reuse a ready binding or resume its active preparation. Preparation failure does not change identity or storage status.", "properties": { "model": { "type": "string", "examples": [ "seedance-2.5-cl" ] }, "config_id": { "type": "string", "maxLength": 0, "description": "Reserved calling-configuration scope. Omit it; a non-empty value is currently rejected." }, "operation": { "type": "string", "enum": [ "create", "rebuild", "refresh" ], "description": "Optional explicit operation. create creates an initial binding; rebuild recreates an invalid binding; refresh queries an existing valid reference. A failed refresh does not overwrite an otherwise valid binding." } }, "required": [ "model" ] }, "AssetOperationResponse": { "type": "object", "additionalProperties": false, "description": "Active in the current MoonApiX asset API release. Minimal asset operation result; full asset name/type metadata and legacy readiness aliases are not required.", "properties": { "object": { "type": "string", "const": "asset" }, "asset_id": { "type": "string" }, "asset_ref": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "syncing", "ready", "failed", "disabled" ] }, "storage": { "$ref": "#/components/schemas/AssetStorage" }, "preparation": { "$ref": "#/components/schemas/AssetPreparation" }, "request_id": { "type": "string" }, "trace_id": { "type": "string" } }, "required": [ "object", "asset_id", "status", "storage" ] }, "AssetPrepareResponse": { "allOf": [ { "$ref": "#/components/schemas/AssetOperationResponse" }, { "type": "object", "required": [ "preparation" ] } ] }, "OfficialAssetFields": { "type": "object", "additionalProperties": false, "description": "Allowlisted official asset details. IDs are scoped to resources already registered to the authenticated account and selected public model. Media signatures may appear only in the HTTPS download URL.", "properties": { "asset_id": { "type": "string", "description": "Original Volcengine asset ID returned by official asset detail." }, "group_id": { "type": "string", "description": "Registered official group ID used for ID resolution. Keep this value when a separate observed_group_id is returned." }, "observed_group_id": { "type": "string", "description": "Optional official group ID observed in the latest detail when it differs from the registered group_id. This value does not replace group_id for ID resolution." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Current official HTTPS media download URL, which may contain a short-lived media signature. May be omitted while processing. Re-read detail to refresh; do not treat it as permanent storage. Some media URLs reject HEAD with 403 but support anonymous Range GET 206 and GET 200. Never send the MoonApiX API key to this URL." }, "status": { "type": "string", "description": "Detail responses report official resource status. List and preparation responses may instead report local reference or preparation summaries such as ready, pending or deletion_pending. None of these values replaces preparation.generation_ready for the selected public model." }, "name": { "type": "string", "description": "Official resource name. Updates may take several minutes to become visible in detail." }, "description": { "type": "string", "description": "Official group description." }, "asset_type": { "type": "string", "description": "Official media type." }, "group_type": { "type": "string", "description": "Official group type." }, "created_at": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Creation time as reported in detail." }, "updated_at": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Update time as reported in detail." }, "moderation": { "type": "object", "additionalProperties": false, "properties": { "strategy": { "type": "string", "description": "Reported moderation strategy; not a client-selectable creation option." } } } } }, "OfficialAssetResponse": { "type": "object", "required": [ "object", "asset_id", "group_id", "upstream" ], "properties": { "object": { "type": "string", "const": "asset" }, "asset_id": { "type": "string", "description": "MoonApiX asset ID." }, "asset_ref": { "type": "string", "description": "MoonApiX asset reference." }, "group_id": { "type": "string", "description": "MoonApiX group ID." }, "upstream": { "$ref": "#/components/schemas/OfficialAssetFields" }, "deleted": { "type": "boolean", "description": "true after the official asset is deleted; does not delete the MoonApiX asset or stored media." }, "generation_ready": { "type": "boolean" }, "preparation": { "$ref": "#/components/schemas/AssetPreparation" } } }, "OfficialAssetGroupResponse": { "type": "object", "required": [ "object", "group_id", "upstream" ], "properties": { "object": { "type": "string", "const": "asset_group" }, "group_id": { "type": "string", "description": "MoonApiX group ID." }, "upstream": { "$ref": "#/components/schemas/OfficialAssetFields" }, "deleted": { "type": "boolean", "description": "true after the official group is deleted. The MoonApiX group is retained." } } }, "OfficialAssetList": { "type": "object", "required": [ "object", "data", "total", "offset", "limit" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialAssetResponse" } }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "OfficialAssetGroupList": { "type": "object", "required": [ "object", "data", "total", "offset", "limit" ], "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OfficialAssetGroupResponse" } }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "OfficialAssetResolveRequest": { "type": "object", "required": [ "model" ], "anyOf": [ { "required": [ "upstream_asset_id" ] }, { "required": [ "upstream_group_id" ] } ], "properties": { "model": { "type": "string", "description": "Public MoonApiX model whose asset scope will be searched." }, "upstream_asset_id": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Known official asset ID returned for a resource owned by this account. After trimming surrounding whitespace, the ID must contain at most 191 UTF-8 bytes and no whitespace, control characters, forward slash or backslash." }, "upstream_group_id": { "type": "string", "minLength": 1, "maxLength": 191, "description": "Known registered official group ID. Use the returned group_id rather than a differing observed_group_id. After trimming surrounding whitespace, the ID must contain at most 191 UTF-8 bytes and no whitespace, control characters, forward slash or backslash." } } }, "OfficialAssetResolution": { "type": "object", "required": [ "object", "asset_id", "asset_ref", "group_id", "upstream" ], "properties": { "object": { "type": "string", "const": "asset_resolution" }, "asset_id": { "type": "string", "description": "MoonApiX asset ID; empty string for a group-only resolution." }, "asset_ref": { "type": "string", "description": "MoonApiX reference; empty string for a group-only resolution." }, "group_id": { "type": "string", "description": "MoonApiX group ID." }, "upstream": { "$ref": "#/components/schemas/OfficialAssetFields" }, "trace_id": { "type": "string" }, "request_id": { "type": "string" } } }, "OfficialAssetPreparationResponse": { "type": "object", "additionalProperties": false, "description": "Official asset preparation result. Official IDs may be absent while creation is pending. For the current model, inspect preparation.generation_ready when present, or the explicit generation_ready field in compatible responses. Download URLs are read from official asset detail.", "properties": { "object": { "type": "string", "const": "asset" }, "asset_id": { "type": "string" }, "asset_ref": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "syncing", "ready", "failed", "disabled" ] }, "storage": { "$ref": "#/components/schemas/AssetStorage" }, "preparation": { "$ref": "#/components/schemas/AssetPreparation" }, "request_id": { "type": "string" }, "trace_id": { "type": "string" }, "upstream": { "$ref": "#/components/schemas/OfficialAssetFields" }, "group_id": { "type": "string", "description": "MoonApiX group ID when included in a compatible response." }, "generation_ready": { "type": "boolean", "description": "Compatible readiness projection when returned. Use the same public model scope." } }, "required": [ "object", "asset_id", "asset_ref" ] } }, "examples": { "Seedance25LastFrameCreate": { "summary": "seedance-2.5-cl: request the generated last frame", "description": "This 4-second, 480p, 16:9 text-only workflow with return_last_frame=true has been verified in production. Use the public task ID returned on creation to poll either query endpoint. Check status and error before reading content.video_url or content.last_frame_url. The prompt and example.com URLs in response examples are placeholders.", "value": { "model": "seedance-2.5-cl", "content": [ { "type": "text", "text": "A calm ocean scene with a slow camera movement." } ], "duration": 4, "resolution": "480p", "ratio": "16:9", "return_last_frame": true } }, "Seedance25LastFrameNormalizedSuccess": { "summary": "Successful normalized query with a last-frame image", "description": "Illustrative subset of a successful response. Both id and task_id are the public task ID from creation. content.last_frame_url is optional, contains an image rather than the video, and is available without raw response mode. Do not assume a permanent URL or PNG format; inspect the downloaded Content-Type.", "value": { "id": "task_xxx", "task_id": "task_xxx", "model": "seedance-2.5-cl", "status": "succeeded", "content": { "video_url": "https://example.com/result.mp4", "last_frame_url": "https://example.com/result-last-frame.jpg" }, "error": null } }, "Seedance25LastFrameCompatibleSuccess": { "summary": "Successful compatible query with a last-frame image", "description": "Illustrative subset of a successful compatible response. id is the public task ID from creation; this response does not require a separate task_id field. Check status and error first. content.last_frame_url is optional, needs no raw response mode, and may use a temporary URL or an image format other than PNG.", "value": { "id": "task_xxx", "model": "seedance-2.5-cl", "status": "succeeded", "content": { "video_url": "https://example.com/result.mp4", "last_frame_url": "https://example.com/result-last-frame.jpg" }, "error": null } }, "SGStandard1080PCompleted": { "summary": "SG standard 1080p completed task (illustrative fields)", "value": { "id": "task_xxx", "object": "video", "model": "seedance-2.0-sg", "status": "completed", "resolution": "1080p", "duration": 4, "url": "https://example.com/result.mp4" } }, "SGStandard4KCompleted": { "summary": "SG standard 4k completed task (illustrative fields)", "value": { "id": "task_xxx", "object": "video", "model": "seedance-2.0-sg", "status": "completed", "resolution": "4k", "duration": 4, "url": "https://example.com/result.mp4" } } }, "parameters": { "AssetContract": { "name": "MoonApiX-Asset-Contract", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "v2" ] }, "description": "Active contract contract; available only after the corresponding service release. Set v2 to request the explicit Asset / Storage / Preparation projection. Omit the header for the legacy contract or an enabled compatibility transition. Historical records keep their lifecycle semantics. Empty, repeated, or unsupported header values are rejected." } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/api/asset/createMedia": { "post": { "tags": [ "Assets" ], "summary": "Create media asset", "operationId": "createMediaAsset", "description": "Creates a reusable media asset from a URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateMediaRequest" }, "examples": { "basic": { "summary": "Create media asset", "value": { "url": "https://example.com/video.mp4", "type": "video", "name": "product-video" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "url": "https://yoozi-us2.oss-us-west-1.aliyuncs.com/3576339b-08f2-424b-8778-cc013b9b730c.jpg", "name": "ref-video.mp4", "assetType": "Image" } } } } } }, "responses": { "200": { "description": "Asset response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/asset/get": { "get": { "tags": [ "Assets" ], "summary": "Get media asset", "operationId": "getMediaAsset", "description": "Returns media asset information by query parameter.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "examples": { "success": { "summary": "Success response", "value": { "object": "asset", "id": "asset_xxx", "asset_id": "asset_xxx", "group_id": "group_xxx", "asset_ref": "Asset://asset_xxx", "reference": "Asset://asset_xxx", "asset_type": "image", "status": "ready", "sync_status": "ready", "preparation_status": "ready", "generation_ready": true, "source_url": "https://example.com/ref.png", "url": "https://example.com/ref.png", "content": { "type": "image_url", "image_url": { "url": "Asset://asset_xxx" }, "role": "reference_image" }, "review_status": "succeeded", "review_passed": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/ideogram/describe": { "post": { "tags": [ "Ideogram" ], "summary": "Describe image", "operationId": "describeIdeogramImage", "description": "Describe image using Ideogram-compatible parameters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramRequest" }, "examples": { "basic": { "summary": "Describe image", "value": { "image_url": "https://example.com/input.png" } } } } } }, "responses": { "200": { "description": "Describe image response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramDescribeResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": "2000-01-23T04:56:07Z", "data": [ { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g", "style_type": "REALISTIC" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/ideogram/generate": { "post": { "tags": [ "Ideogram" ], "summary": "Generate image", "operationId": "createIdeogramImage", "description": "Generate image using Ideogram-compatible parameters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramRequest" }, "examples": { "basic": { "summary": "Generate image", "value": { "prompt": "A clean product photo on a white background.", "aspect_ratio": "1:1" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "image_request": { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "aspect_ratio": "ASPECT_10_16", "model": "V_2", "magic_prompt_option": "AUTO" } } } } } } }, "responses": { "200": { "description": "Generate image response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": "2000-01-23T04:56:07Z", "data": [ { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g", "style_type": "REALISTIC" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/ideogram/remix": { "post": { "tags": [ "Ideogram" ], "summary": "Remix image", "operationId": "remixIdeogramImage", "description": "Remix image using Ideogram-compatible parameters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramRequest" }, "examples": { "basic": { "summary": "Remix image", "value": { "prompt": "Keep the product, change the background to a studio scene.", "image_url": "https://example.com/input.png" } } } } } }, "responses": { "200": { "description": "Remix image response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": "2000-01-23T04:56:07Z", "data": [ { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g", "style_type": "REALISTIC" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/ideogram/upscale": { "post": { "tags": [ "Ideogram" ], "summary": "Upscale image", "operationId": "upscaleIdeogramImage", "description": "Upscale image using Ideogram-compatible parameters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramRequest" }, "examples": { "basic": { "summary": "Upscale image", "value": { "image_url": "https://example.com/input.png" } } } } } }, "responses": { "200": { "description": "Upscale image response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeogramResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": "2000-01-23T04:56:07Z", "data": [ { "prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "resolution": "1024x1024", "is_image_safe": true, "seed": 12345, "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g", "style_type": "REALISTIC" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/insight-face/swap": { "post": { "tags": [ "Midjourney" ], "summary": "Submit face swap task", "operationId": "submitMidjourneyFaceSwap", "description": "Submit face swap task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit face swap task", "value": { "sourceBase64": "data:image/png;base64,...", "targetBase64": "data:image/png;base64,..." } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712211887200849" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/action": { "post": { "tags": [ "Midjourney" ], "summary": "Submit action task", "operationId": "submitMidjourneyAction", "description": "Submit action task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit action task", "value": { "taskId": "task_xxx", "customId": "upsample_1" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "notifyHook": "", "customId": "MJ::JOB::upsample::2::3dbbd469-36af-4a0f-8f02-df6c579e7011", "taskId": "14001934816969359", "state": "" } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712203779820810" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/blend": { "post": { "tags": [ "Midjourney" ], "summary": "Submit blend task", "operationId": "submitMidjourneyBlend", "description": "Submit blend task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit blend task", "value": { "base64Array": [ "data:image/png;base64,..." ] } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "mode": "RELAX", "notifyHook": "", "base64Array": [ "data:image/png;base64,xxx1", "data:image/png;base64,xxx2" ], "dimensions": "SQUARE", "state": "" } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712204995849323" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/describe": { "post": { "tags": [ "Midjourney" ], "summary": "Submit describe task", "operationId": "submitMidjourneyDescribe", "description": "Submit describe task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit describe task", "value": { "base64": "data:image/png;base64,..." } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "mode": "RELAX", "notifyHook": "", "base64": "data:image/png;base64,xxx", "state": "" } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712205491372224" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/imagine": { "post": { "tags": [ "Midjourney" ], "summary": "Submit imagine task", "operationId": "submitMidjourneyImagine", "description": "Submit imagine task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit imagine task", "value": { "prompt": "A futuristic city at sunrise --ar 16:9" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "mode": "RELAX", "notifyHook": "", "base64Array": [ "data:image/png;base64,xxx1", "data:image/png;base64,xxx2" ], "prompt": "Cat", "state": "" } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712158011464906" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/modal": { "post": { "tags": [ "Midjourney" ], "summary": "Submit modal task", "operationId": "submitMidjourneyModal", "description": "Submit modal task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit modal task", "value": { "taskId": "task_xxx", "maskBase64": "data:image/png;base64,..." } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "maskBase64": "data:image/png;base64,xxx1", "prompt": "Cat", "taskId": "1712204995849323" } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712204995849323" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/shorten": { "post": { "tags": [ "Midjourney" ], "summary": "Submit shorten task", "operationId": "submitMidjourneyShorten", "description": "Submit shorten task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit shorten task", "value": { "prompt": "A long detailed image prompt." } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "mode": "RELAX", "notifyHook": "", "prompt": "Cat", "state": "" } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "Submit success", "result": "1712211887200849" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/upload-discord-images": { "post": { "tags": [ "Midjourney" ], "summary": "Upload images", "operationId": "uploadMidjourneyImages", "description": "Uploads image files for later Midjourney-compatible tasks.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } } }, "required": [ "files" ] } } } }, "responses": { "200": { "description": "Upload response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "success", "result": [ "https://cdn.discordapp.com/attachments/1235333617467789395/1237020337057828935/1508569645328691200.jpg?ex=663a2077&is=6638cef7&hm=991c97a66f00ee5b5714848ccf0cded22929d58f0d809f0057c71c4b29ee469d&" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/submit/video": { "post": { "tags": [ "Midjourney" ], "summary": "Submit video task", "operationId": "submitMidjourneyVideo", "description": "Submit video task and returns a task identifier.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneySubmitRequest" }, "examples": { "basic": { "summary": "Submit video task", "value": { "taskId": "task_xxx" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "mode": "FAST", "prompt": "a car", "taskId": "1712204995849323", "index": 1 } } } } } }, "responses": { "200": { "description": "Task submit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/task/list-by-condition": { "post": { "tags": [ "Midjourney" ], "summary": "List tasks by condition", "operationId": "listMidjourneyTasksByCondition", "description": "Returns Midjourney-compatible tasks that match the request conditions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer", "minimum": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": true }, "examples": { "basic": { "summary": "List tasks", "value": { "ids": [ "task_xxx" ] } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "ids": [ "1712158011464906" ] } } } } } }, "responses": { "200": { "description": "Task list response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/mj/task/{id}/fetch": { "get": { "tags": [ "Midjourney" ], "summary": "Fetch task", "operationId": "fetchMidjourneyTask", "description": "Returns one Midjourney-compatible task by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "id": "1712158011464906", "action": "IMAGINE", "status": "SUCCESS", "prompt": "A futuristic city at sunrise --ar 16:9", "imageUrl": "https://example.com/mj/result.png", "progress": "100%", "buttons": [ { "label": "U1", "customId": "MJ::JOB::upsample::1::demo" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/mj/task/{id}/image-seed": { "get": { "tags": [ "Midjourney" ], "summary": "Get image seed", "operationId": "getMidjourneyImageSeed", "description": "Returns seed information for a completed image task.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Seed response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MidjourneyImageSeedResponse" }, "examples": { "success": { "summary": "Success response", "value": { "code": 1, "description": "", "result": "" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sora/v1/characters": { "post": { "tags": [ "Video Compatibility" ], "summary": "Create video character", "operationId": "createVideoCharacter", "description": "Create video character using MoonApiX video parameters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "basic": { "summary": "Create video character", "value": { "model": "seedance-2.0-kz-fast", "prompt": "A cinematic product video.", "duration": 5, "aspect_ratio": "16:9" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "url": "https://filesystem.site/cdn/20251030/javYrU4etHVFDqg8by7mViTWHlMOZy.mp4", "timestamps": "1,3" } } } } } }, "responses": { "200": { "description": "Created video task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/assets": { "post": { "tags": [ "Assets" ], "summary": "Create asset identity (V2)", "operationId": "createAssetV2", "x-release-status": "active", "description": "Active in the current MoonApiX asset API release. Send MoonApiX-Asset-Contract: v2 to select strict identity creation. The version header is required for this documented operation; omitting it uses the separate legacy upload contract. Exactly one URL or file is verified before a stable immutable identity is created. storage.enabled is optional archive intent, not a storage success flag. Creation does not prepare the asset for any model. An archive failure can still return 201 with an established identity and storage.status=failed; do not recreate that identity solely to retry storage. The original input URL is not exposed.", "parameters": [ { "name": "MoonApiX-Asset-Contract", "in": "header", "required": true, "schema": { "type": "string", "const": "v2" }, "description": "Required to select the active strict V2 asset-creation contract." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateV2JSONRequest" }, "examples": { "create": { "summary": "Create identity and request archive", "value": { "url": "https://example.com/reference.png", "type": "image", "storage": { "enabled": true } } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AssetCreateV2MultipartRequest" } } } }, "responses": { "201": { "description": "Asset identity created; inspect independent storage status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetV2" }, "examples": { "result": { "summary": "Asset identity created; inspect independent storage status.", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "status": "ready", "storage": { "status": "ready" }, "type": "image", "name": "reference.png", "content_type": "image/png", "size": 245678 } } } } } }, "400": { "description": "Invalid source/options or unsupported/legacy V2 fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Asset group not found or disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Asset group domain does not accept this content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Input exceeds the platform media size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Asset identity could not be saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Assets" ], "summary": "List assets", "operationId": "listAssets", "description": "Returns assets available to the authenticated account. Use group_id to filter one customer-defined group. In the current MoonApiX asset API release, the optional MoonApiX-Asset-Contract: v2 header selects the three-layer projection; V2 assets can also retain that projection without the header. Lists do not compute model preparation: query an individual asset with an explicit model before interpreting readiness. Historical unmigrated records retain their existing status meaning. Non-empty model or config_id is not supported for V2 list queries.", "parameters": [ { "$ref": "#/components/parameters/AssetContract" }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Asset group ID. If provided, only assets in this group are returned." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "image", "audio", "video", "file" ] } } ], "responses": { "200": { "description": "Asset list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssets" }, "examples": { "success": { "summary": "Success response", "value": { "object": "list", "total": 1, "count": 1, "data": [ { "id": "asset_xxx", "object": "asset", "type": "image", "url": "https://example.com/assets/asset_xxx.png", "reference": "Asset://asset_xxx", "status": "ready", "sync_status": "ready", "preparation_status": "ready", "generation_ready": true, "trace_id": "2026060301010100000000000000000000", "created_at": 1710000000, "review_status": "succeeded", "review_passed": true } ] }, "description": "Historical legacy example without an explicit model scope. Do not use its aliases as a V2 preparation result." }, "v2List": { "summary": "Active V2 list omits model preparation", "description": "In the current MoonApiX asset API release, send MoonApiX-Asset-Contract: v2. Query one asset with model to compute preparation.", "value": { "object": "list", "total": 1, "count": 1, "data": [ { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "type": "image", "status": "ready", "storage": { "status": "ready" } } ] } } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported contract value, query scope, or non-empty config_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/assets/uploads": { "post": { "tags": [ "Assets" ], "summary": "Upload asset", "operationId": "uploadAsset", "description": "Create a reusable asset. Upload and preparation are free; generation is billed by its model. The V2 asset contract is active in the current asset API release. Omit MoonApiX-Asset-Contract for the legacy contract or an enabled three-layer compatibility transition. In that transition, mode=asset also archives a trusted content snapshot; source_url/url/oss_url aliases expose only a verified safe managed URL, never the original input URL. Historical unmigrated responses keep their previous status and URL meaning. mode remains a legacy request field: oss archives, asset prepares for model use, and both requests both. With MoonApiX-Asset-Contract: v2, this alias instead performs strict identity creation from one URL or one file, optionally archives when storage.enabled=true, returns 201, and rejects legacy model/mode/urls/purpose/subject_type/role fields. V2 creation does not prepare for a model; use the explicit prepare operation. Asset identity, storage and preparation are independent. generation_ready is scoped to an explicit model/current calling configuration and does not guarantee immediate generation or change normal scheduling. Long-term retention follows a separate storage contract.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "anyOf": [ { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ] }, "purpose": { "type": "string", "examples": [ "video_reference" ] }, "mode": { "type": "string", "enum": [ "oss", "asset", "both" ], "description": "Legacy mode: oss requests archiving, asset requests model preparation, both requests both. In the enabled three-layer transition, asset also archives a trusted snapshot; responses return only verified managed URL aliases. The explicit v2 header rejects this field." }, "group_id": { "type": "string", "description": "Asset group ID. If omitted, the default group is used." }, "model": { "type": "string", "description": "Legacy target public model for preparation. Three-layer readiness is evaluated in this explicit model/current calling scope. Shared compatible asset preparation may be reused without re-upload; identity is stable and capability checks still apply.", "examples": [ "seedance-2.5-cl" ] } }, "required": [ "file", "type" ], "description": "Legacy request selected when the version header is omitted. Enabled three-layer compatibility handling can retain this request shape; it does not accept this shape with an explicit v2 header." }, { "$ref": "#/components/schemas/AssetCreateV2MultipartRequest" } ], "description": "Header selects the contract: omitted uses the legacy/transition input; MoonApiX-Asset-Contract: v2 requires the strict V2 schema." }, "examples": { "ossUpload": { "summary": "Create a MoonApiX OSS test URL", "value": { "file": "@reference.png", "type": "image", "purpose": "video_reference", "mode": "oss", "group_id": "group_xxx" } }, "modelAssetAdvanced": { "summary": "Advanced: create hosted URL and asset reference from uploaded file", "value": { "file": "@reference.png", "type": "image", "purpose": "video_reference", "mode": "both", "group_id": "group_xxx", "model": "seedance-2.0-kz-fast" } }, "v2Create": { "summary": "Active strict V2 create with version header", "description": "Send MoonApiX-Asset-Contract: v2. Creates identity and optionally storage; preparation is performed separately.", "value": { "file": "@reference.png", "type": "image", "storage": "{\"enabled\":true}" } } } }, "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "group_id": { "type": "string", "description": "Asset group ID. If omitted, the default group is used." }, "model": { "type": "string", "examples": [ "seedance-2.0-kz-fast", "seedance-2.0-sz", "seedance-2.0-sz-fast", "seedance-2.0-sz-mini", "seedance-2.5-sz", "seedance-2.5-cl", "seedance-2.0-cl-mini", "seedance-2.0-cl-b-fast", "seedance-2.0-cl-b-mini", "seedance-2.0-gl-mini", "doubao-seedance-2-0-260128" ], "description": "Legacy target public model for preparation. Three-layer readiness is evaluated in this explicit model/current calling scope. Shared compatible asset preparation may be reused without re-upload; identity is stable and capability checks still apply." }, "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ] }, "purpose": { "type": "string", "examples": [ "video_reference" ] }, "mode": { "type": "string", "enum": [ "asset", "oss", "both" ], "description": "Legacy mode: oss requests archiving, asset requests model preparation, both requests both. In the enabled three-layer transition, asset also archives a trusted snapshot; responses return only verified managed URL aliases. The explicit v2 header rejects this field." } }, "required": [ "type", "mode" ], "description": "Legacy request selected when the version header is omitted. Enabled three-layer compatibility handling can retain this request shape; it does not accept this shape with an explicit v2 header." }, { "$ref": "#/components/schemas/AssetCreateV2JSONRequest" } ], "description": "Header selects the contract: omitted uses the legacy/transition input; MoonApiX-Asset-Contract: v2 requires the strict V2 schema." }, "examples": { "urlAsset": { "summary": "Create an Asset:// reference for a supported model", "value": { "model": "seedance-2.0-kz-fast", "mode": "asset", "type": "image", "url": "https://example.com/reference.png" }, "description": "Legacy request without an explicit v2 header. Preparation must be confirmed for the target model before generation." }, "groupAsset": { "summary": "Create an asset in a group", "value": { "model": "seedance-2.0-kz-fast", "mode": "asset", "type": "image", "group_id": "group_xxx", "url": "https://example.com/reference.png" } }, "clAsset": { "summary": "Create an Asset:// reference for seedance-2.0-cl family", "description": "Legacy request without an explicit v2 header. Preparation must be confirmed for the target model before generation.", "value": { "model": "seedance-2.0-cl-fast", "mode": "asset", "type": "image", "url": "https://example.com/reference.png" } }, "clMiniVideoAsset": { "summary": "Create a video Asset:// reference for seedance-2.0-cl-mini", "description": "Legacy request without an explicit v2 header. Preparation must be confirmed for the target model before generation.", "value": { "model": "seedance-2.0-cl-mini", "mode": "asset", "type": "video", "purpose": "reference_video", "role": "reference_video", "url": "https://example.com/reference.mp4" } }, "glAsset": { "summary": "Create an Asset:// reference for the seedance-2.0-gl family", "description": "Legacy request without an explicit v2 header. Preparation must be confirmed for the target model before generation.", "value": { "model": "seedance-2.0-gl-mini", "mode": "asset", "type": "image", "purpose": "video_reference", "url": "https://example.com/reference.png" } }, "v2Create": { "summary": "Active strict V2 create with version header", "description": "Send MoonApiX-Asset-Contract: v2. Creates identity and optionally storage; preparation is performed separately.", "value": { "url": "https://example.com/reference.png", "type": "image", "storage": { "enabled": true } } } } } } }, "responses": { "200": { "description": "Legacy upload or enabled three-layer compatibility result (without explicit v2 header). Historical status meaning is not automatically changed.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "count": { "type": "integer" } }, "required": [ "object", "data", "count" ] } ] }, "examples": { "compatibility": { "summary": "Active contract: identity ready while preparation is processing", "value": { "id": "asset_xxx", "asset_id": "asset_xxx", "object": "asset", "type": "image", "asset_ref": "Asset://asset_xxx", "status": "ready", "storage": { "status": "ready" }, "source_url": "https://moonapix.com/assets/public/fixture/reference.png", "url": "https://moonapix.com/assets/public/fixture/reference.png", "preparation": { "model": "seedance-2.5-cl", "status": "processing", "generation_ready": false, "review_status": "unknown" }, "preparation_status": "processing", "sync_status": "processing", "generation_ready": false, "review_status": "unknown", "review_passed": false } } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "201": { "description": "The V2 asset contract is active in the current asset API release. Strict V2 identity created when the version header is v2. Storage failure does not erase the successful identity; read storage.status/error. No model preparation is performed by creation.", "headers": { "MoonApiX-Asset-Contract": { "schema": { "type": "string", "const": "v2" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetV2" }, "examples": { "identity": { "summary": "Identity created with archive requested", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "type": "image", "status": "ready", "storage": { "status": "ready" } } } } } } }, "400": { "description": "Unsupported asset creation or invalid upload request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "$ref": "#/components/parameters/AssetContract" } ] } }, "/v1/assets/{asset_id}": { "get": { "tags": [ "Assets" ], "summary": "Get asset", "operationId": "getAsset", "description": "Returns one asset by ID. If group_id is provided, the asset must belong to that group. In the current MoonApiX asset API release, optional MoonApiX-Asset-Contract: v2 selects the explicit three-layer projection, and new V2 assets retain that projection without the header. Only an explicit model adds nested preparation for the current calling configuration. generation_ready=true means one permitted path is prepared; it does not promise immediate generation or alter normal scheduling. Unknown review is neutral. GET observes this scope without starting or polling preparation; POST /prepare advances it. Historical unmigrated lifecycle states retain their prior meaning.", "parameters": [ { "$ref": "#/components/parameters/AssetContract" }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional group check. If the asset is not in this group, the API returns not found." }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Explicit public target model for preparation under the current calling configuration. V2 omits preparation when absent. The enabled legacy transition aliases refer to this same scope." }, { "name": "config_id", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 0 }, "description": "Reserved scope. Omit it; any non-empty config_id is currently rejected rather than ignored." } ], "responses": { "200": { "description": "Asset detail.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/AssetV2" } ] }, "examples": { "success": { "summary": "Success response", "value": { "id": "asset_xxx", "object": "asset", "type": "image", "url": "https://example.com/assets/asset_xxx.png", "reference": "Asset://asset_xxx", "status": "ready", "sync_status": "ready", "preparation_status": "ready", "generation_ready": true, "trace_id": "2026060301010100000000000000000000", "created_at": 1710000000, "review_status": "succeeded", "review_passed": true }, "description": "Historical legacy projection only; no V2 model-scoped readiness is implied by this example." }, "v2Identity": { "summary": "Active contract: identity query without model", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "type": "image", "status": "ready", "storage": { "status": "not_started" } } }, "v2Scoped": { "summary": "Active contract: explicit model preparation", "description": "Query with model=seedance-2.5-cl; the readiness result applies to this model and the current calling configuration.", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "type": "image", "status": "ready", "storage": { "status": "ready" }, "preparation": { "model": "seedance-2.5-cl", "status": "ready", "generation_ready": true, "review_status": "unknown" } } } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported contract value, query scope, or non-empty config_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Assets" ], "summary": "Update asset", "operationId": "updateAsset", "description": "Updates an asset name, description, or group for the authenticated account. Send at least one field. The target group must belong to the same account, have status enabled, and share the asset domain. Returns the actual asset object: existing V2 assets retain the V2 representation, while historical assets use the compatibility representation. This operation does not start asset preparation or a generation task.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Asset name; it must not be empty after trimming whitespace." }, "description": { "type": "string", "description": "Asset description; an empty string clears it." }, "group_id": { "type": "string", "description": "Target group ID. It must belong to the same account, be enabled, and share the asset domain." } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "description" ] }, { "required": [ "group_id" ] } ] }, "examples": { "updateAsset": { "summary": "Update asset details and move to a group in the same domain", "value": { "name": "reference-updated.png", "description": "Updated project material", "group_id": "group_xxx" } } } } } }, "responses": { "200": { "description": "Updated asset object.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/AssetV2" } ] } } } }, "400": { "description": "Invalid JSON, asset or group ID, empty name, or no supported update field." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The asset does not exist, is disabled, or belongs to another account; the target group may also be missing, disabled, or owned by another account." }, "409": { "description": "The target group domain differs from the asset domain; error code group_domain_mismatch." } } }, "delete": { "tags": [ "Assets" ], "summary": "Soft-delete asset", "operationId": "deleteAsset", "description": "Sets an asset owned by the authenticated account to status disabled and returns the actual asset object with deleted=true. Existing V2 assets retain the V2 representation, while historical assets use the compatibility representation. Soft deletion retains the record, historical associations, and certification records. It does not remove managed OSS files or call an external certification service to delete records, and does not promise to revoke issued URLs or cancel existing tasks.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Soft-deleted asset object with status=disabled and deleted=true.", "content": { "application/json": { "schema": { "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/AssetV2" } ] }, { "type": "object", "properties": { "status": { "const": "disabled" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "status", "deleted" ] } ] }, "example": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "group_id": "group_xxx", "type": "image", "status": "disabled", "storage": { "status": "ready" }, "deleted": true } } } }, "400": { "description": "Invalid asset ID." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The asset does not exist, belongs to another account, or is already disabled. Repeated deletion also returns 404." } } } }, "/v1/audio/speech": { "post": { "tags": [ "Audio" ], "summary": "Create speech", "operationId": "createSpeech", "description": "Creates audio from input text.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioSpeechRequest" }, "examples": { "basic": { "summary": "Create speech", "value": { "model": "tts-1", "input": "Welcome to MoonApiX.", "voice": "alloy", "response_format": "mp3" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "model": "tts-1", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy" } } } } } }, "responses": { "200": { "description": "Audio file response." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/audio/transcriptions": { "post": { "tags": [ "Audio" ], "summary": "Create transcription", "operationId": "createTranscription", "description": "Transcribes an audio file into text.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string", "examples": [ "whisper-1" ] }, "language": { "type": "string" }, "prompt": { "type": "string" }, "response_format": { "type": "string", "examples": [ "json" ] } }, "required": [ "file", "model" ] }, "examples": { "moonapixExample": { "summary": "MoonApiX example", "value": { "file": "@audio.mp3", "temperature": 0 } } } } } }, "responses": { "200": { "description": "Transcription response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" }, "examples": { "success": { "summary": "Success response", "value": { "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/audio/translations": { "post": { "tags": [ "Audio" ], "summary": "Create translation", "operationId": "createTranslation", "description": "Translates an audio file into English text.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "model": { "type": "string", "examples": [ "whisper-1" ] }, "prompt": { "type": "string" }, "response_format": { "type": "string", "examples": [ "json" ] } }, "required": [ "file", "model" ] }, "examples": { "moonapixExample": { "summary": "MoonApiX example", "value": { "file": "@audio.mp3", "temperature": 0 } } } } } }, "responses": { "200": { "description": "Translation response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" }, "examples": { "success": { "summary": "Success response", "value": { "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/chat/completions": { "post": { "tags": [ "OpenAI-compatible" ], "summary": "Create chat completion", "operationId": "createChatCompletion", "description": "Creates an OpenAI-compatible chat completion request. Supported model IDs are managed by MoonApiX.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "moonapix-chat" ] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" }, "minItems": 1 }, "stream": { "type": "boolean", "default": false }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1 } }, "required": [ "model", "messages" ] }, "examples": { "basic": { "summary": "Basic request", "value": { "model": "moonapix-chat", "messages": [ { "role": "user", "content": "Generate a short product tagline." } ] } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "model": "jimeng-4.5", "messages": [ { "role": "user", "content": "Draw a cat." } ], "stream": true } } } } } }, "responses": { "200": { "description": "Chat completion response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" }, "examples": { "success": { "summary": "Success response", "value": { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/embeddings": { "post": { "tags": [ "Embeddings" ], "summary": "Create embeddings", "operationId": "createEmbeddings", "description": "Creates vector embeddings for text input.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingRequest" }, "examples": { "basic": { "summary": "Create embedding", "value": { "model": "moonapix-embedding", "input": "MoonApiX developer documentation" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "model": "text-embedding-ada-002", "input": "The food was delicious and the waiter..." } } } } } }, "responses": { "200": { "description": "Embedding response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingResponse" }, "examples": { "success": { "summary": "Success response", "value": { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023, -0.0093, 0.0041 ], "index": 0 } ], "model": "moonapix-embedding", "usage": { "prompt_tokens": 8, "total_tokens": 8 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/images/edits": { "post": { "tags": [ "Images" ], "summary": "Create image edit", "operationId": "createImageEdit", "description": "Creates an edited image from an input image and prompt. Multipart file upload is the default request form. Some API key groups also support application/json with one public image URL or an array of public image URLs; availability, accepted image count, and limits depend on the current API key group and selected model. For GPT Image, use gpt-image-2-pro or gpt-image-2-vip for higher-quality edits; both models support the same pixel-size calling rules.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageEditRequest" }, "examples": { "moonapixExample": { "summary": "MoonApiX example", "value": { "image": "@image.png", "mask": "@mask.png", "prompt": "A cute baby sea otter wearing a beret.", "n": "2", "size": "1024x1024", "response_format": "url" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ImageJSONEditRequest" }, "examples": { "singleImageURL": { "summary": "Synchronous image edit with one public URL when supported by the current group", "value": { "model": "gpt-image-2", "prompt": "Keep the product and change the background to a clean studio scene.", "image": "https://example.com/product.png", "size": "1024x1024", "n": 1 } }, "multipleImageURLs": { "summary": "Synchronous multi-image edit when supported by the current group and model", "value": { "model": "gpt-image-2", "prompt": "Keep the subject from the first image and use the colors and details from the second image.", "image": [ "https://example.com/subject.png", "https://example.com/style.png" ], "size": "1024x1024", "n": 1 } } } } } }, "responses": { "200": { "description": "Image edit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/images/edits/async": { "post": { "tags": [ "Images" ], "summary": "Create async image edit task", "operationId": "createAsyncImageEdit", "description": "Creates an async image edit task using the MoonApiX canonical image field. Pass one public image URL or Base64 Data URL string, or an array of strings for multiple references. Omit optional fields such as quality to use the selected model's default behavior. For direct multipart file uploads, use /v1/images/edits. Query /v1/images/tasks/{task_id} until completion, and read error.message when status is failed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageAsyncEditRequest" }, "examples": { "basic": { "summary": "Async image edit", "value": { "model": "gpt-image-2", "prompt": "Change the background to a clean studio scene.", "image": "https://example.com/product.png", "size": "1024x1024" } }, "multipleImages": { "summary": "Async multi-image edit", "value": { "model": "gpt-image-2", "prompt": "Keep the main subject from the first image and use the colors and details from the second image.", "image": [ "https://example.com/subject.png", "https://example.com/style.png" ], "size": "1024x1024", "n": 1 } } } } } }, "responses": { "200": { "description": "Async image edit task submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "id": "task_xxx", "object": "image.edit", "created": 1711234567, "status": "queued", "progress": 3, "model": "gpt-image-2-pro" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/images/tasks/{task_id}": { "get": { "tags": [ "Images" ], "summary": "Get async image task", "operationId": "getAsyncImageTask", "description": "Returns an async image task owned by the authenticated account. Check status first. When status is succeeded, read data[].url.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Image task ID returned by /v1/images/generations/async or /v1/images/edits/async." } ], "responses": { "200": { "description": "Image task response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "id": "task_xxx", "object": "image.generation", "created": 1711234567, "status": "succeeded", "progress": 100, "model": "gpt-image-2", "data": [ { "url": "https://media.moonapix.com/image/example.png" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Image task not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/images/tasks/{task_id}/content": { "get": { "tags": [ "Images" ], "summary": "Get async image task content", "operationId": "getAsyncImageTaskContent", "description": "Redirects to the generated image URL when the async image task succeeded. API integrations should usually query /v1/images/tasks/{task_id} and save data[].url.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Image task ID." } ], "responses": { "200": { "description": "Generated image content when served directly.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Redirect to generated image URL." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Image task not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Task is not ready." } } } }, "/v1/images/generations": { "post": { "tags": [ "Images" ], "summary": "Create image generation", "operationId": "createImageGeneration", "description": "Creates an image generation request. GPT Image models include gpt-image-2, gpt-image-2-pro, and gpt-image-2-vip. gpt-image-2-pro and gpt-image-2-vip support the same resolution and size calling rules.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "gpt-image-2" ], "description": "Image model name, for example gpt-image-2, gpt-image-2-pro, or gpt-image-2-vip." }, "prompt": { "type": "string", "description": "Image description. Include subject, scene, style, composition, aspect ratio, and intended use when relevant." }, "size": { "type": "string", "examples": [ "1024x1024" ], "description": "Output size. gpt-image-2 supports aspect-ratio values such as 16:9 or 1K pixel values such as 1024x1024. gpt-image-2-pro and gpt-image-2-vip use the same 1K to 4K pixel-size calling rules, such as 1024x1024, 2048x2048, or 3840x2160." }, "n": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 } }, "required": [ "model", "prompt" ] }, "examples": { "basic": { "summary": "Basic request", "value": { "model": "gpt-image-2", "prompt": "A clean product mockup on a white studio table.", "size": "1024x1024" } } } } } }, "responses": { "200": { "description": "Image generation response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": 1711234567, "data": [ { "url": "https://example.com/images/generated-image.png", "revised_prompt": "A clean product photo on a white background." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/images/generations/async": { "post": { "tags": [ "Images" ], "summary": "Create async image generation task", "operationId": "createAsyncImageGeneration", "description": "Creates an async image generation task. The response returns a task ID immediately. Query /v1/images/tasks/{task_id} until status is succeeded or failed. Async results return image URLs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageAsyncGenerationRequest" }, "examples": { "basic": { "summary": "Async image generation", "value": { "model": "gpt-image-2", "prompt": "A clean product mockup on a white studio table.", "size": "1024x1024", "n": 1 } }, "geminiProAsync": { "summary": "Gemini Pro image async generation", "description": "Available only when the current API key group and model capability allow image async tasks.", "value": { "model": "gemini-3-pro-image-preview", "prompt": "A premium outdoor lifestyle advertising storyboard proposal board, Chinese typography, warm evening light.", "size": "16:9", "resolution": "4K", "n": 1 } } } } } }, "responses": { "200": { "description": "Async image task submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTaskResponse" }, "examples": { "success": { "summary": "Success response", "value": { "id": "task_xxx", "object": "image.generation", "created": 1711234567, "status": "queued", "progress": 3, "model": "gpt-image-2" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/images/variations": { "post": { "tags": [ "Images" ], "summary": "Create image variation", "operationId": "createImageVariation", "description": "Creates image variations from an input image.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageVariationRequest" }, "examples": { "moonapixExample": { "summary": "MoonApiX example", "value": { "image": "@image.png", "n": "2", "size": "1024x1024", "response_format": "url" } } } } } }, "responses": { "200": { "description": "Image variation response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResponse" }, "examples": { "success": { "summary": "Success response", "value": { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/messages": { "post": { "tags": [ "Messages" ], "summary": "Create message", "operationId": "createMessage", "description": "Creates a Claude-compatible message request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "moonapix-claude" ] }, "max_tokens": { "type": "integer" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } } }, "required": [ "model", "messages" ] }, "examples": { "basic": { "summary": "Create message", "value": { "model": "moonapix-claude", "max_tokens": 512, "messages": [ { "role": "user", "content": "Write a short welcome message." } ] } } } } } }, "responses": { "200": { "description": "Message response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List models", "operationId": "listModels", "description": "Returns models available to the authenticated MoonApiX account.", "responses": { "200": { "description": "Model list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "examples": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } }, "required": [ "object", "data" ] }, "examples": { "success": { "summary": "Success response", "value": { "object": "list", "data": [ { "id": "moonapix-chat", "object": "model", "owned_by": "moonapix" }, { "id": "gpt-image-2", "object": "model", "owned_by": "moonapix" }, { "id": "gemini-3.1-flash-image-preview", "object": "model", "owned_by": "moonapix" }, { "id": "gemini-3-pro-image-preview", "object": "model", "owned_by": "moonapix" }, { "id": "nano-banana-2", "object": "model", "owned_by": "moonapix" }, { "id": "nano-banana-pro", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-kz-fast", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-sz", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-sz-fast", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-sz-mini", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.5-sz", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.5-cl", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-cl-fast", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-cl", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-cl-mini", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-cl-b-fast", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-cl-b-mini", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-gl", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-gl-fast", "object": "model", "owned_by": "moonapix" }, { "id": "seedance-2.0-gl-mini", "object": "model", "owned_by": "moonapix" }, { "id": "doubao-seedance-2-0-260128", "object": "model", "owned_by": "moonapix" }, { "id": "doubao-seedance-2-0-fast-260128", "object": "model", "owned_by": "moonapix" }, { "id": "doubao-seedance-2-0-mini-260615", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-dj-fast", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-b-720p-fast", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-b-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-c-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-d-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-e-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-wc-f-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-gl-a-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-gl-a-720p-fast", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.5-gl-a", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-ld-a", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-ld-b", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-am-720p-fast", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-il-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-me-a-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-me-b-720p", "object": "model", "owned_by": "moonapix" }, { "id": "moon-2.0-me-a-fast", "object": "model", "owned_by": "moonapix" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/models/{modelid}": { "get": { "tags": [ "Models" ], "summary": "Retrieve model", "operationId": "retrieveModel", "description": "Returns information for one model.", "parameters": [ { "name": "modelid", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "nano-banana-2" ] } } ], "responses": { "200": { "description": "Model detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" }, "examples": { "success": { "summary": "Success response", "value": { "id": "gpt-3.5-turbo-instruct", "object": "model", "created": 1686935002, "owned_by": "openai" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/responses": { "post": { "tags": [ "Responses" ], "summary": "Create response", "operationId": "createResponse", "description": "Creates an OpenAI-compatible response request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "moonapix-chat" ] }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ] }, "stream": { "type": "boolean", "default": false } }, "required": [ "model", "input" ] }, "examples": { "basic": { "summary": "Create response", "value": { "model": "moonapix-chat", "input": "Write a short welcome message." } } } } } }, "responses": { "200": { "description": "Response result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/responses/compact": { "post": { "tags": [ "Responses" ], "summary": "Compact Responses context", "operationId": "compactResponse", "description": "Creates a compacted Responses context for long conversations when the selected model supports context compaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "moonapix-chat-openai-compact" ] }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } } ], "description": "Conversation content to compact." }, "instructions": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ], "description": "Optional instructions for the compacted output." }, "previous_response_id": { "type": "string", "description": "Previous response ID when continuing an existing Responses flow." } }, "required": [ "model" ] }, "examples": { "basic": { "summary": "Compact context", "value": { "model": "moonapix-chat-openai-compact", "input": "Summarize the conversation so far and keep decisions, constraints, and next actions." } } } } } }, "responses": { "200": { "description": "Compacted response context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tasks/{task_id}": { "get": { "tags": [ "Tasks" ], "summary": "Get task", "operationId": "getTask", "description": "Returns the latest status and output for an async task, including trace_id/request_id/trace metadata and task_chain when available.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Task ID returned by an async generation endpoint." } ], "responses": { "200": { "description": "Task detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "succeeded": { "summary": "Successful task", "value": { "id": "task_xxx", "task_id": "task_xxx", "status": "succeeded", "progress": "100%", "result": { "audio_url": "https://example.com/result.mp3" } } }, "failed": { "summary": "Failed task", "value": { "id": "task_xxx", "task_id": "task_xxx", "status": "failed", "progress": "100%", "fail_reason": "The request parameters are invalid.", "error": { "message": "The request parameters are invalid." } } } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Task not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/video/generations": { "post": { "tags": [ "Video Compatibility" ], "summary": "Create video task", "operationId": "createVideoTaskCompatibility", "description": "Create video task using MoonApiX video parameters. SH public models seedance-2.0-sh, seedance-2.0-sh-fast, seedance-2.0-sh-mini and seedance-2.5-sh accept both canonical references[] and official-compatible content[] (choose one). Supported generation options include generate_audio, draft, draft_task_id and off_peak; top-level > input > metadata precedence preserves false. Unsupported options such as seed, frames, watermark, tools, camera_fixed and service_tier return errors. SH accepts callback_url only on POST /api/v3/contents/generations/tasks. MoonApiX delivers the callback; delivery has not completed live validation. SH requests on /v1/videos or /v1/video/generations reject callback_url. Use polling in the verified workflow. Use SH public model IDs to select this model line; official model names may participate in shared model scheduling. Compatibility does not imply every official feature is available. See the SH model page for capability and validation boundaries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "textToVideo": { "summary": "Text to video", "value": { "model": "seedance-2.0-kz-fast", "prompt": "A cinematic product video with slow camera movement.", "duration": 5, "aspect_ratio": "16:9" } }, "firstLastFrame": { "summary": "First and last frame", "value": { "model": "sora-v3-fast", "prompt": "Create a smooth transition between the first and last frame.", "seconds": "5", "images": [ { "url": "https://example.com/first-frame.jpg", "role": "first_frame" }, { "url": "https://example.com/last-frame.jpg", "role": "last_frame" } ], "aspect_ratio": "16:9" } }, "contentItems": { "summary": "Multimedia content items", "value": { "model": "seedance-2.0-kz", "prompt": "Keep the character identity and generate a stage singing video.", "duration": 5, "ratio": "16:9", "resolution": "720p", "generate_audio": true, "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/character.png" }, "role": "reference_image" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/song.mp3" }, "role": "reference_audio" } ] } }, "szTextToVideo": { "summary": "Seedance SZ text to video with audio", "description": "SZ models use the official ratio, duration, resolution, generate_audio, and watermark fields. generate_audio=true requests an audio track.", "value": { "model": "seedance-2.0-sz-fast", "prompt": "An orange cat stretches beside a window. Slow camera push-in, natural afternoon light, realistic style.", "duration": 4, "ratio": "16:9", "resolution": "480p", "generate_audio": true, "watermark": false } }, "szImageToVideoSilent": { "summary": "Seedance SZ image to video without audio", "description": "Set generate_audio=false when a silent result is required.", "value": { "model": "seedance-2.0-sz-mini", "prompt": "Let the person turn naturally and smile at the camera. Preserve their clothing and facial features.", "duration": 4, "aspect_ratio": "9:16", "resolution": "480p", "generate_audio": false, "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/person.png", "alias": "person" } ] } }, "szMixedMedia": { "summary": "Seedance SZ image, video, and audio references", "description": "Audio references require at least one image or video reference. Use stable public media URLs or a model-ready Asset:// reference.", "value": { "model": "seedance-2.0-sz", "prompt": "Use the appearance of @person, follow the camera movement in @motion, and use @music as background music.", "duration": 8, "ratio": "16:9", "resolution": "720p", "generate_audio": true, "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/person.png", "alias": "person" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "motion" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "music" } ] } }, "szFirstLastFrame": { "summary": "Seedance SZ first and last frame", "value": { "model": "seedance-2.0-sz", "prompt": "Transition smoothly from indoors to outdoors, maintaining subject and color continuity.", "duration": 6, "ratio": "16:9", "resolution": "1080p", "generate_audio": false, "content": [ { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/first.jpg" } }, { "type": "image_url", "role": "last_frame", "image_url": { "url": "https://example.com/last.jpg" } } ] } }, "szOfficialContent": { "summary": "Seedance SZ official-shaped content request", "description": "The SZ public model names accept official-shaped content[], ratio, resolution, duration, generate_audio, and watermark fields. Use either content[] or references[], not both.", "value": { "model": "seedance-2.0-sz-fast", "content": [ { "type": "text", "text": "An early morning seaside scene, with the camera moving steadily forward." } ], "duration": 4, "ratio": "16:9", "resolution": "720P", "generate_audio": false, "watermark": false, "service_tier": "default", "priority": 0 } }, "cl25OfficialAsset": { "summary": "Seedance 2.5 CL official-shaped authenticated image request", "description": "Accepts content[], ratio, resolution, duration, and generate_audio on /v1/videos or /api/v3/contents/generations/tasks. Use the MoonApiX model ID seedance-2.5-cl and a ready asset prepared for this model. Failed Asset:// resolution returns an error, never a public-URL fallback. Choose either content[] or references[]; model-specific limits still apply.", "value": { "model": "seedance-2.5-cl", "content": [ { "type": "text", "text": "The woman in the image says \"cheese\" to the camera during a 360-degree orbiting camera move." }, { "type": "image_url", "role": "reference_image", "alias": "Image1", "image_url": { "url": "Asset://asset_xxx" } } ], "duration": 4, "ratio": "9:16", "resolution": "480p", "generate_audio": true, "output_format": "mp4" } }, "sz25MixedAsset": { "summary": "Seedance 2.5 SZ image, audio, and video assets", "description": "Prepare each Asset:// reference with mode=asset and wait for generation_ready=true and preparation_status=ready before creating the task.", "value": { "model": "seedance-2.5-sz", "content": [ { "type": "image_url", "role": "reference_image", "image_url": { "url": "Asset://asset_image_demo" } }, { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "Asset://asset_audio_demo" } }, { "type": "video_url", "role": "reference_video", "video_url": { "url": "Asset://asset_video_demo" } } ], "duration": 5, "ratio": "16:9", "resolution": "720P", "generate_audio": true, "watermark": false } }, "moonapixAsset": { "summary": "Use explicit MoonApiX asset reference when supported", "value": { "model": "seedance-2.0-kz-fast", "prompt": "Animate the product with a slow rotating camera.", "image": "Asset://asset_xxx", "duration": 5 } }, "sgMixedReference": { "summary": "SG: 4 seconds, 2 images, 1 audio and 1 video", "description": "Use accessible HTTPS media URLs. SG requests with images default to image_source_mode=asset; asset is recommended for person photos, while direct_url is explicit and may be rejected by image privacy review. SG 2.0 standard supports 1080P and 4K; SG 2.0 Fast/Mini support 480p or 720p; SG 2.5 supports 480p, 720p, and 1080P. A single image must keep role=reference_image. Billing uses completion_tokens with resolution and video-input tiers; obtain current prices from the console or pricing API.", "value": { "model": "seedance-2.5-sg", "prompt": "Preserve the subjects in @图片1 and @图片2, follow the camera motion in @视频1, and incorporate the atmosphere of @音频1.", "image_source_mode": "asset", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-1.png" }, { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-2.png" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/reference-audio.wav" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/reference-video.mp4" } ], "size": "1080p", "aspect_ratio": "16:9", "duration": 4, "generate_audio": true } }, "sgOfficialMixedReference": { "summary": "SG: official-compatible mixed references, 4 seconds", "description": "Use the MoonApiX API key and SG public model ID. Choose content[] or references[], not both. Poll the returned public task ID and check status/error before reading content.video_url. Preserve the returned downloadable media URL, including its query parameters.", "value": { "model": "seedance-2.5-sg", "content": [ { "type": "text", "text": "Preserve the subjects in @图片1 and @图片2, follow the camera motion in @视频1, and incorporate the atmosphere of @音频1." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-1.png" } }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-2.png" } }, { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/reference-audio.wav" } }, { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://example.com/reference-video.mp4" } } ], "resolution": "1080p", "ratio": "16:9", "duration": 4, "generate_audio": true } }, "ntPersonReference": { "summary": "NT: 4-second public person reference image", "description": "Replace the example URL with an anonymously accessible image. The same 4-second request works with any of the four NT public model IDs.", "value": { "model": "seedance-2.5-nt", "prompt": "The person in the reference image turns naturally; keep their appearance consistent and the camera steady.", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/person-reference.jpg" } ], "size": "720p", "aspect_ratio": "16:9", "duration": 4, "generate_audio": false, "watermark": false } }, "ntOfficialPersonReference": { "summary": "NT: official-shaped 4-second image reference", "description": "Use a MoonApiX API Key and public NT model ID. Poll the returned public task ID.", "value": { "model": "seedance-2.5-nt", "content": [ { "type": "text", "text": "The person in the reference image turns naturally; keep their appearance consistent and the camera steady." }, { "type": "image_url", "image_url": { "url": "https://example.com/person-reference.jpg" }, "role": "reference_image" } ], "resolution": "720p", "ratio": "16:9", "duration": 4, "generate_audio": false, "watermark": false } }, "sgOfficialImagesAudio": { "$ref": "#/paths/~1api~1v3~1contents~1generations~1tasks/post/requestBody/content/application~1json/examples/sgOfficialImagesAudio" }, "sh25Text": { "summary": "SH 2.5: 1080P, 4-second text-to-video", "description": "Validated request format; the prompt is illustrative. Poll status and error before using a result URL.", "value": { "model": "seedance-2.5-sh", "prompt": "A white ceramic cup on a table, smooth camera movement, soft daylight.", "size": "1080P", "aspect_ratio": "16:9", "seconds": "4", "generate_audio": true, "off_peak": false } }, "sh25OfficialText": { "summary": "SH 2.5: official-compatible content[]", "description": "Validated request format; the prompt is illustrative. Poll status and error before using a result URL.", "value": { "model": "seedance-2.5-sh", "content": [ { "type": "text", "text": "A white ceramic cup on a table, smooth camera movement, soft daylight." } ], "resolution": "1080P", "ratio": "16:9", "duration": 4, "generate_audio": true, "off_peak": false } } } } } }, "responses": { "200": { "description": "Created video task.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] }, "examples": { "success": { "summary": "Success response", "value": { "code": "success", "data": { "task_id": "task_xxx", "status": "running" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/video/generations/{task_id}": { "get": { "tags": [ "Video Compatibility" ], "summary": "Get video task", "operationId": "getVideoTaskCompatibility", "description": "Get video task and result information. Check status first; read result URLs only when status is succeeded. Failed or unfinished responses may omit output and result URL fields.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Video task response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] }, "examples": { "success": { "summary": "Success response", "value": { "code": "success", "data": { "task_id": "task_xxx", "status": "succeeded", "progress": "100%", "result_url": "https://moonapix.com/v1/videos/task_xxx/content", "data": { "video_url": "https://moonapix.com/v1/videos/task_xxx/content" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v3/contents/generations/tasks": { "post": { "tags": [ "Video Compatibility" ], "summary": "Create a compatible Seedance task", "operationId": "createCompatibleSeedanceTask", "description": "Creates a Seedance-compatible asynchronous video task. The request keeps the official content[], ratio, resolution, duration, generate_audio, callback_url, and related field names. Use MoonApiX public model IDs enabled for the account, such as seedance-2.0-sz, seedance-2.0-sz-fast, seedance-2.0-sz-mini, seedance-2.5-sz, seedance-2.5-cl, seedance-2.0-cl-b-fast, and seedance-2.0-cl-b-mini. Use a MoonApiX API Key with either this path or /v1/videos; keep the same public model ID. Request-shape compatibility does not imply support for every official advanced parameter; use the selected model page for limits. For seedance-2.5-cl, Asset:// references must be prepared for this model and ready; failed resolution returns an error instead of falling back to a public URL. For CL-B mixed-media content[], include a unique alias on every image, video, and audio item. NT public model IDs seedance-2.0-nt, seedance-2.0-nt-fast, seedance-2.0-nt-mini, and seedance-2.5-nt also support content[], ratio, resolution, duration, generate_audio, and watermark. NT uses polling; callback_url and other advanced capabilities are not part of the verified NT workflow. See https://docs.moonapix.com/api/videos/seedance-2-0-nt for model limits. SH public models seedance-2.0-sh, seedance-2.0-sh-fast, seedance-2.0-sh-mini and seedance-2.5-sh accept both canonical references[] and official-compatible content[] (choose one). Supported generation options include generate_audio, draft, draft_task_id and off_peak; top-level > input > metadata precedence preserves false. Unsupported options such as seed, frames, watermark, tools, camera_fixed and service_tier return errors. SH accepts callback_url only on POST /api/v3/contents/generations/tasks. MoonApiX delivers the callback; delivery has not completed live validation. SH requests on /v1/videos or /v1/video/generations reject callback_url. Use polling in the verified workflow. Use SH public model IDs to select this model line; official model names may participate in shared model scheduling. Compatibility does not imply every official feature is available. See the SH model page for capability and validation boundaries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "cl25LastFrame": { "$ref": "#/components/examples/Seedance25LastFrameCreate" }, "text": { "summary": "Official-shaped text request", "value": { "model": "doubao-seedance-2-0-fast-260128", "content": [ { "type": "text", "text": "An early morning seaside scene, with the camera moving steadily forward." } ], "duration": 4, "ratio": "16:9", "resolution": "720P", "generate_audio": false, "watermark": false } }, "mixedAssets": { "summary": "Image, audio, and video references", "description": "Use ready Asset:// references or stable public URLs. Audio requires an image or video reference.", "value": { "model": "doubao-seedance-2-0-260128", "content": [ { "type": "image_url", "role": "reference_image", "image_url": { "url": "Asset://asset_image_demo" } }, { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "Asset://asset_audio_demo" } }, { "type": "video_url", "role": "reference_video", "video_url": { "url": "Asset://asset_video_demo" } } ], "duration": 5, "ratio": "16:9", "resolution": "720P", "generate_audio": true } }, "cl25OfficialAsset": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/cl25OfficialAsset" }, "clBMixedAssets": { "summary": "CL-B official-shaped mixed-media request", "description": "Use seedance-2.0-cl-b-fast or seedance-2.0-cl-b-mini. CL-B follows the official Seedance 2.0 Fast / Mini parameter contract through content[], ratio, resolution, duration, generate_audio, watermark, seed, and callback_url. Give each media item a unique alias to preserve prompt-addressable reference binding; apply the selected official model's capability matrix for values and limits.", "value": { "model": "seedance-2.0-cl-b-fast", "content": [ { "type": "text", "text": "Let the subject move naturally while the camera moves steadily forward." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference.png" }, "alias": "Image1" }, { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://example.com/motion.mp4" }, "alias": "Video1" }, { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/music.mp3" }, "alias": "Audio1" } ], "duration": 4, "ratio": "16:9", "resolution": "720P", "generate_audio": true, "watermark": false } }, "sgOfficialMixedReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/sgOfficialMixedReference" }, "ntPersonReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/ntPersonReference" }, "ntOfficialPersonReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/ntOfficialPersonReference" }, "sgOfficialImagesAudio": { "summary": "SG 2.0: official-compatible 6 images + 1 audio, no video", "description": "Reference audio can accompany images without a reference video. This media combination completed a real 480p / 16:9 / 10-second request with generated audio; example.com URLs and the prompt below are illustrative placeholders. Keep each reference_image and reference_audio role and the image order. Exact voice or dialogue matching is not guaranteed. Probe the downloaded media for actual dimensions and duration: one verified result was 864x496 and 10.08 seconds. This does not establish every model or media limit. Check task status and error before using content.video_url.", "value": { "model": "seedance-2.0-sg", "content": [ { "type": "text", "text": "Use @图片1 and @图片6 as character references. Preserve the object features from @图片2, @图片3 and @图片5, and the environment and lighting from @图片4. Let the character from @图片6 speak using the voice characteristics in @音频1, with steady natural camera movement." }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-1.png" } }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-2.png" } }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-3.png" } }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-4.png" } }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-5.png" } }, { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/reference-6.png" } }, { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/reference-audio.mp3" } } ], "duration": 10, "execution_expires_after": 3600, "generate_audio": true, "ratio": "16:9", "resolution": "480p", "watermark": false } }, "dreaminaSeedance20": { "summary": "Dreamina Seedance 2.0: compatible request", "value": { "model": "dreamina-seedance-2-0-260128", "content": [ { "type": "text", "text": "Create a smooth cinematic transition using the two reference images." }, { "type": "image_url", "image_url": { "url": "https://example.com/reference-1.jpg" }, "role": "reference_image" }, { "type": "image_url", "image_url": { "url": "https://example.com/reference-2.jpg" }, "role": "reference_image" } ], "duration": 15, "ratio": "16:9", "resolution": "720p" } }, "dreaminaSeedance25": { "summary": "Dreamina Seedance 2.5: compatible request", "value": { "model": "dreamina-seedance-2-5-260628", "content": [ { "type": "text", "text": "Create a smooth cinematic transition using the two reference images." }, { "type": "image_url", "image_url": { "url": "https://example.com/reference-1.jpg" }, "role": "reference_image" }, { "type": "image_url", "image_url": { "url": "https://example.com/reference-2.jpg" }, "role": "reference_image" } ], "duration": 30, "ratio": "16:9", "resolution": "720p" } }, "sh25Text": { "summary": "SH 2.5: 1080P, 4-second text-to-video", "description": "Validated request format; the prompt is illustrative. Poll status and error before using a result URL.", "value": { "model": "seedance-2.5-sh", "prompt": "A white ceramic cup on a table, smooth camera movement, soft daylight.", "size": "1080P", "aspect_ratio": "16:9", "seconds": "4", "generate_audio": true, "off_peak": false } }, "sh25OfficialText": { "summary": "SH 2.5: official-compatible content[]", "description": "Validated request format; the prompt is illustrative. Poll status and error before using a result URL.", "value": { "model": "seedance-2.5-sh", "content": [ { "type": "text", "text": "A white ceramic cup on a table, smooth camera movement, soft daylight." } ], "resolution": "1080P", "ratio": "16:9", "duration": 4, "generate_audio": true, "off_peak": false } } } } } }, "responses": { "200": { "description": "Created compatible video task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "success": { "summary": "Task accepted", "value": { "id": "task_xxx", "status": "queued", "model": "doubao-seedance-2-0-fast-260128" } } } } } }, "400": { "description": "Invalid or conflicting parameters." }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Video Compatibility" ], "summary": "List compatible Seedance tasks", "operationId": "listCompatibleSeedanceTasks", "description": "Lists compatible Seedance tasks belonging to the authenticated account within the supported history window.", "parameters": [ { "name": "page_num", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 } }, { "name": "filter.status", "in": "query", "schema": { "type": "string" } }, { "name": "filter.model", "in": "query", "schema": { "type": "string" } }, { "name": "filter.service_tier", "in": "query", "schema": { "type": "string" } }, { "name": "filter.task_ids", "in": "query", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Compatible task list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "total": { "type": "integer" } }, "required": [ "items", "total" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v3/contents/generations/tasks/{task_id}": { "get": { "tags": [ "Video Compatibility" ], "summary": "Get a compatible Seedance task", "operationId": "getCompatibleSeedanceTask", "description": "Returns task status and result fields in the compatible response shape. id is the MoonApiX public task ID returned on creation; a separate task_id field is not required in this response. Check status and error before reading content.video_url or other result fields. For seedance-2.5-cl requested with return_last_frame=true, a successful query may include the generated image at content.last_frame_url without raw response mode. This optional image field differs from the input last_frame_url reference and may be absent when not requested, not produced, or unavailable for safe public access. Determine its image format from Content-Type; PNG is not guaranteed. For NT, poll until a successful terminal status with no error before using the result URL. Preserve the complete returned URL, including any query parameters, and download before expiry. Refund entries may represent the difference between reserved quota and actual token settlement rather than task failure.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Compatible task response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "cl25LastFrameSuccess": { "$ref": "#/components/examples/Seedance25LastFrameCompatibleSuccess" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Task not found." } } }, "delete": { "tags": [ "Video Compatibility" ], "summary": "Cancel a compatible Seedance task", "operationId": "cancelCompatibleSeedanceTask", "description": "Cancels an unfinished compatible Seedance task owned by the authenticated account.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Task not found." } } } }, "/v1/videos": { "post": { "tags": [ "Video Compatibility" ], "summary": "Create video task", "operationId": "createVideoTask", "description": "Creates an async video generation task. /v1/videos is the unified task entry point, but model input fields differ. Covered Seedance models may use MoonApiX references[] with media_type, role, url, and alias. images[]/videos[]/audios[] and content[] remain compatibility fields; other models should follow their model-specific fields. Production clients must pass public media URLs from their own storage. Use /v1/assets/uploads mode=oss only for temporary integration testing, or mode=asset for supported model asset references; both preparation operations are free. MoonApiX OSS does not guarantee long-term retention, URL lifetime, availability, or a production storage SLA. Uploaded assets are not automatically attached to later video tasks; each request must explicitly pass a public URL or Asset://asset_xxx in a field supported by the selected model. For URL-based reference media, prefer direct public media URLs with real file extensions such as .png, .mp4, .wav, or .mp3, without login, cookies, extra authorization headers, one-time download pages, or complex anti-hotlinking requirements. input_type only selects the input mode. SH public models seedance-2.0-sh, seedance-2.0-sh-fast, seedance-2.0-sh-mini and seedance-2.5-sh accept both canonical references[] and official-compatible content[] (choose one). Supported generation options include generate_audio, draft, draft_task_id and off_peak; top-level > input > metadata precedence preserves false. Unsupported options such as seed, frames, watermark, tools, camera_fixed and service_tier return errors. SH accepts callback_url only on POST /api/v3/contents/generations/tasks. MoonApiX delivers the callback; delivery has not completed live validation. SH requests on /v1/videos or /v1/video/generations reject callback_url. Use polling in the verified workflow. Use SH public model IDs to select this model line; official model names may participate in shared model scheduling. Compatibility does not imply every official feature is available. See the SH model page for capability and validation boundaries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "cl25LastFrame": { "$ref": "#/components/examples/Seedance25LastFrameCreate" }, "cl25OfficialAsset": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/cl25OfficialAsset" }, "textToVideo": { "summary": "Text to video", "value": { "model": "seedance-2.0-kz-fast", "prompt": "A cinematic product video with slow camera movement.", "duration": 5, "aspect_ratio": "16:9" } }, "contentItems": { "summary": "Multimedia content items", "value": { "model": "seedance-2.0-kz", "prompt": "Keep the character identity and generate a stage singing video.", "duration": 5, "ratio": "16:9", "resolution": "720p", "generate_audio": true, "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/character.png" }, "role": "reference_image" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/song.mp3" }, "role": "reference_audio" } ] } }, "moonapixAsset": { "summary": "Use explicit MoonApiX asset reference when supported", "value": { "model": "seedance-2.0-kz-fast", "prompt": "Animate the product with a slow rotating camera.", "images": [ { "url": "Asset://asset_xxx", "role": "reference_image" } ], "duration": 5 } }, "grokImagine10": { "summary": "Grok Imagine 1.0 video", "value": { "model": "grok-imagine-1.0-video", "prompt": "A cinematic sunrise over snowy mountains with a slow drone push-in.", "video_config": { "video_length": 6, "aspect_ratio": "16:9", "resolution": "HD" } } }, "grokImagine15PreviewImage": { "summary": "Grok Imagine 1.5 preview image to video", "value": { "model": "grok-imagine-video-1.5-preview", "prompt": "Animate the subject with a gentle camera move while preserving identity.", "input_reference": "https://example.com/source.jpg", "seconds": "15", "aspect_ratio": "16:9", "size": "720P" } }, "grokImagine15Super": { "summary": "Grok Imagine 1.5 720p image to video", "value": { "model": "grok-imagine-1.5-video-super-720p", "prompt": "Move the camera forward smoothly with cinematic lighting.", "input_reference": "https://example.com/source.jpg", "size": "1280x720" } }, "grokVideo15": { "summary": "grok-video-1.5 first-frame image to video", "value": { "model": "grok-video-1.5", "prompt": "Keep the subject identity stable while adding a gentle camera move.", "input_reference": "https://example.com/first-frame.jpg", "seconds": "15", "aspect_ratio": "16:9", "size": "720P" } }, "grokImageVideo": { "summary": "grok-image-video multi-reference video", "value": { "model": "grok-image-video", "prompt": "Blend multiple references into one consistent cinematic scene.", "reference_image_urls": [ "https://example.com/ref-1.jpg", "https://example.com/ref-2.jpg" ], "seconds": "15", "aspect_ratio": "3:4", "size": "1080P" } }, "seedanceReferenceAsset": { "summary": "Seedance reference video with explicit uploaded asset", "description": "Use this after /v1/assets/uploads returns generation_ready=true. input_type=reference alone does not load an uploaded asset.", "value": { "model": "seedance-2.0-kz-fast", "prompt": "The woman in the image says \"cheese\" to the camera during a 360-degree orbiting camera move.", "mode": "fast", "resolution": "720p", "ratio": "adaptive", "duration": 5, "generate_audio": true, "watermark": false, "web_search": false, "input_type": "reference", "generation_type": "video", "content": [ { "type": "image_url", "role": "reference_image", "image_url": { "url": "Asset://asset_xxx" } } ] } }, "moon_wc_reference": { "summary": "moon-2.0-wc series with image, video, and audio references[]", "description": "Use references[] with customer-owned direct public URLs for production, or MoonApiX OSS test URLs during integration testing. This model supports up to 12 reference files total in one request; within that total, use up to 9 images, 3 videos, and 3 audios. One full mixed combination is 6 images, 3 videos, and 3 audios. Omitted aliases are assigned sequentially per media type, so prompts may use @图片1, @视频1, and @音频1. moon-2.0-wc-720p supports 4 through 14 seconds; a client value of 15 is accepted for compatibility and generated as 14 seconds. If audio is background music, say so explicitly in the prompt.", "value": { "model": "moon-2.0-wc-720p", "prompt": "Preserve the appearance in @图片1, follow the movement in @视频1, and use @音频1 as background music.", "duration": 15, "ratio": "9:16", "resolution": "720p", "references": [ { "media_type": "image", "role": "character_reference", "url": "https://example.com/character.png" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3" } ] } }, "moon_wc_c_reference": { "summary": "moon-2.0-wc-c-720p image-reference video", "description": "Supports people, text-only requests, or up to 9 image references. Video and audio references are rejected. The accepted target duration is 4 through 15 seconds; verify the actual media duration after success. Supported ratios are 16:9, 9:16, 1:1, 4:3, and 3:4.", "value": { "model": "moon-2.0-wc-c-720p", "prompt": "Create a clean product video using @product as the visual reference.", "duration": 8, "ratio": "16:9", "resolution": "720p", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/product.png", "alias": "product" } ] } }, "moon_wc_d_reference": { "summary": "moon-2.0-wc-d-720p mixed-reference video", "description": "Supports people, text-only requests, or up to 4 images, 3 videos, and 1 audio, with no more than 8 references total. An audio reference requires at least one image or video. The accepted target duration is 4 through 15 seconds; verify the actual media duration after success. Supported ratios are 16:9, 9:16, 1:1, 4:3, and 3:4.", "value": { "model": "moon-2.0-wc-d-720p", "prompt": "Use @subject as the subject, follow @motion, and use @music as background music.", "duration": 15, "ratio": "9:16", "resolution": "720p", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/subject.png", "alias": "subject" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "motion" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "music" } ] } }, "moon_wc_e_reference": { "summary": "moon-2.0-wc-e-720p mixed-reference video", "description": "Supports people, text-only requests, or up to 4 images, 3 videos, and 1 audio, with no more than 8 references total. An audio reference requires at least one image or video. The accepted target duration is 4 through 15 seconds; verify the actual media duration after success. Supported ratios are 16:9, 9:16, 1:1, 4:3, and 3:4.", "value": { "model": "moon-2.0-wc-e-720p", "prompt": "Keep @subject consistent, follow @motion, and use @music as background music.", "duration": 15, "ratio": "9:16", "resolution": "720p", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/subject.png", "alias": "subject" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "motion" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "music" } ] } }, "moon_wc_f_reference": { "summary": "moon-2.0-wc-f-720p text-only or mixed-reference video", "description": "Supports people and text-only requests. Reference requests support up to 9 images, 3 videos, and 3 audios, with no more than 12 references total. An audio reference requires at least one image; a video does not satisfy that image requirement. The accepted target duration is 4 through 15 seconds; verify the actual media duration after success.", "value": { "model": "moon-2.0-wc-f-720p", "prompt": "Keep @subject consistent, follow @motion, and use @music as background music.", "duration": 15, "ratio": "9:16", "resolution": "720p", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/subject.png", "alias": "subject" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "motion" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "music" } ] } }, "seedance_gl_reference": { "summary": "seedance-2.0-gl-mini with mixed references", "description": "Use seedance-2.0-gl, seedance-2.0-gl-fast, or seedance-2.0-gl-mini. The GL series supports up to 9 images, 3 videos, and 3 audios, with no more than 15 references total; audio must be paired with an image or video. Standard supports 480P, 720P, and 1080P; Fast/Mini support 480P and 720P.", "value": { "model": "seedance-2.0-gl-mini", "prompt": "Keep @subject consistent, follow @motion, and use @music as background audio.", "duration": 4, "ratio": "16:9", "resolution": "720P", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/subject.png", "alias": "subject" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "motion" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "music" } ] } }, "moon_gl_reference": { "summary": "moon-2.0-gl series mixed-reference video", "description": "Use moon-2.0-gl-a-720p for the standard model or moon-2.0-gl-a-720p-fast for the fast model. Both support text-only requests or up to 4 images, 3 videos, and 1 audio, with no more than 8 references total. Audio requires at least one image or video. Supported durations are 4 through 15 seconds; supported ratios are 16:9, 9:16, and 1:1.", "value": { "model": "moon-2.0-gl-a-720p-fast", "prompt": "Keep @character consistent, follow @motion, and use @music as background music on a traditional stage with professional camera cuts.", "duration": 15, "ratio": "9:16", "resolution": "720p", "references": [ { "media_type": "image", "role": "character_reference", "url": "https://example.com/character.png", "alias": "character" }, { "media_type": "video", "role": "reference_video", "url": "https://example.com/motion.mp4", "alias": "motion" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/music.mp3", "alias": "music" } ] } }, "moon_ld_b_reference": { "summary": "moon-2.0-ld-b with three person references and background audio", "description": "moon-2.0-ld-b has the same capabilities as moon-2.0-ld-a. Use 720P with an integer duration from 5 through 15 seconds. The model supports up to 9 images, 3 videos, and 3 audios, with no more than 15 reference files total. Audio should be submitted together with an image or video reference.", "value": { "model": "moon-2.0-ld-b", "prompt": "Let @person pose naturally using the reference images, and use @music as background music.", "duration": 14, "ratio": "9:16", "resolution": "720P", "references": [ { "media_type": "image", "role": "character_reference", "url": "https://example.com/person-1.jpg", "alias": "person" }, { "media_type": "image", "role": "reference_image", "url": "https://example.com/person-2.jpg" }, { "media_type": "image", "role": "reference_image", "url": "https://example.com/person-3.jpg" }, { "media_type": "audio", "role": "background_music", "url": "https://example.com/background-music.wav", "alias": "music" } ] } }, "seedance_dj_reference": { "summary": "moon-2.0-dj-fast with image references[]", "description": "Use references[] with image items, up to 9 images. Reference images do not have to be face-only images. This model supports 5, 10, or 15 second durations and does not support video or audio references.", "value": { "model": "moon-2.0-dj-fast", "prompt": "Use @product as the main subject, create a short clean product ad.", "duration": 10, "ratio": "16:9", "resolution": "720P", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/product.png", "alias": "product" } ] } }, "seedance2ClImageToVideo": { "summary": "seedance-2.0-cl-fast image to video", "description": "Use a public image URL or a ready Asset://asset_xxx reference. Uploaded assets are not attached automatically.", "value": { "model": "seedance-2.0-cl-fast", "prompt": "Animate this product image with a slow camera push-in and clean studio lighting.", "image_url": "https://example.com/product.png", "input_reference_role": "first_frame", "duration": 4, "ratio": "16:9", "resolution": "480p", "generate_audio": false, "watermark": false } }, "seedance2ClMiniVideoReference": { "summary": "seedance-2.0-cl-mini with video reference", "description": "CL mini uses the CL parameter system, supports 480p/720p and 4-15 second durations, and can use public URLs or ready Asset:// video references. generate_audio defaults to true when omitted.", "value": { "model": "seedance-2.0-cl-mini", "prompt": "Preserve the motion and camera timing of the reference video, and change the shirt pattern to match the reference image style.", "video_url": "Asset://asset_video_xxx", "image_url": "https://example.com/reference-shirt.png", "duration": 4, "ratio": "16:9", "resolution": "720p" } }, "seedanceAm720pFastReferences": { "summary": "moon-2.0-am-720p-fast with image and background music references[]", "description": "Use references[] with customer-owned direct public URLs for production, or MoonApiX OSS test URLs during integration testing. Audio references should be used together with an image or video reference.", "value": { "model": "moon-2.0-am-720p-fast", "prompt": "Use @audio1 as background music while the woman in @image1 performs challenging fitness movements.", "duration": 15, "ratio": "9:16", "resolution": "720p", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/person.png", "alias": "image1" }, { "media_type": "audio", "role": "reference_audio", "url": "https://example.com/background-music.mp3", "alias": "audio1" } ] } }, "sgMixedReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/sgMixedReference" }, "sgOfficialMixedReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/sgOfficialMixedReference" }, "ntPersonReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/ntPersonReference" }, "ntOfficialPersonReference": { "$ref": "#/paths/~1v1~1video~1generations/post/requestBody/content/application~1json/examples/ntOfficialPersonReference" }, "sgOfficialImagesAudio": { "$ref": "#/paths/~1api~1v3~1contents~1generations~1tasks/post/requestBody/content/application~1json/examples/sgOfficialImagesAudio" }, "dreaminaSeedance20": { "summary": "Dreamina Seedance 2.0: two reference images", "description": "Check model availability in your account. Public image URLs are used; asset ID authentication is not verified. Check status and error before reading any result URL.", "value": { "model": "dreamina-seedance-2-0-260128", "prompt": "Create a smooth cinematic transition using the two reference images.", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-1.jpg" }, { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-2.jpg" } ], "duration": 15, "aspect_ratio": "16:9", "resolution": "720p" } }, "dreaminaSeedance25": { "summary": "Dreamina Seedance 2.5: two reference images", "description": "Check model availability in your account. Public image URLs are used; asset ID authentication is not verified. Check status and error before reading any result URL.", "value": { "model": "dreamina-seedance-2-5-260628", "prompt": "Create a smooth cinematic transition using the two reference images.", "references": [ { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-1.jpg" }, { "media_type": "image", "role": "reference_image", "url": "https://example.com/reference-2.jpg" } ], "duration": 30, "aspect_ratio": "16:9", "resolution": "720p" } }, "sh25Text": { "summary": "SH 2.5: 1080P, 4-second text-to-video", "description": "Validated request format; the prompt is illustrative. Poll status and error before using a result URL.", "value": { "model": "seedance-2.5-sh", "prompt": "A white ceramic cup on a table, smooth camera movement, soft daylight.", "size": "1080P", "aspect_ratio": "16:9", "seconds": "4", "generate_audio": true, "off_peak": false } }, "sh25OfficialText": { "summary": "SH 2.5: official-compatible content[]", "description": "Validated request format; the prompt is illustrative. Poll status and error before using a result URL.", "value": { "model": "seedance-2.5-sh", "content": [ { "type": "text", "text": "A white ceramic cup on a table, smooth camera movement, soft daylight." } ], "resolution": "1080P", "ratio": "16:9", "duration": 4, "generate_audio": true, "off_peak": false } } } } } }, "responses": { "200": { "description": "Created video task.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] }, "examples": { "success": { "summary": "Success response", "value": { "id": "task_xxx", "task_id": "task_xxx", "object": "video", "model": "seedance-2.0-kz-fast", "status": "submitted", "progress": 0, "created_at": 1779830371 } } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/videos/extend": { "post": { "tags": [ "Video Compatibility" ], "summary": "Extend video task", "operationId": "extendVideoTask", "description": "Extend video task using MoonApiX video parameters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "textToVideo": { "summary": "Text to video", "value": { "model": "seedance-2.0-kz-fast", "prompt": "A cinematic product video with slow camera movement.", "duration": 5, "aspect_ratio": "16:9" } }, "firstLastFrame": { "summary": "First and last frame", "value": { "model": "sora-v3-fast", "prompt": "Create a smooth transition between the first and last frame.", "seconds": "5", "first_frame_url": "https://example.com/first-frame.jpg", "last_frame_url": "https://example.com/last-frame.jpg", "aspect_ratio": "16:9" } }, "contentItems": { "summary": "Multimedia content items", "value": { "model": "seedance-2.0-kz", "prompt": "Keep the character identity and generate a stage singing video.", "duration": 5, "ratio": "16:9", "resolution": "720p", "generate_audio": true, "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/character.png" }, "role": "reference_image" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/song.mp3" }, "role": "reference_audio" } ] } }, "moonapixAsset": { "summary": "Use explicit MoonApiX asset reference when supported", "value": { "model": "seedance-2.0-kz-fast", "prompt": "Animate the product with a slow rotating camera.", "image": "Asset://asset_xxx", "duration": 5 } } } } } }, "responses": { "200": { "description": "Created video task.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/videos/{id}": { "get": { "tags": [ "Video Compatibility" ], "summary": "Get video task", "operationId": "getVideoTaskById", "description": "Get video task and result information. Check status first; read result URLs only when status is succeeded. Failed or unfinished responses may omit output and result URL fields.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Video task response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] }, "examples": { "success": { "summary": "Success response", "value": { "object": "video", "id": "dbv1_xxxxx", "status": "in_progress", "progress": 50, "created_at": 1742450000, "model": "seedance-2.0-kz", "seconds": "5", "size": "1280x720" } }, "SGStandard1080PCompleted": { "$ref": "#/components/examples/SGStandard1080PCompleted" }, "SGStandard4KCompleted": { "$ref": "#/components/examples/SGStandard4KCompleted" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/videos/{task_id}": { "get": { "tags": [ "Video Compatibility" ], "summary": "Get video task", "operationId": "getVideoTaskByTaskId", "description": "Get video task and result information. In the default normalized response, id and task_id are the MoonApiX public task ID returned on creation. Some compatibility responses may omit top-level status; if so, read data.status. Check status and error first; read result URLs only when status is succeeded. Failed or unfinished responses may omit output and result URL fields. For seedance-2.5-cl requested with return_last_frame=true, a successful query may include the generated image at content.last_frame_url without raw response mode. This optional image field differs from the input last_frame_url reference and may be absent when not requested, not produced, or unavailable for safe public access. Determine its image format from Content-Type; PNG is not guaranteed. Video result URLs may appear in data.video_url, video_url, url, result_url, output.url, output items, content.video_url, or metadata.url. A successful response may contain an approved direct media URL or a MoonApiX-managed URL. Preserve the complete returned URL, including signed query parameters, and download temporary URLs promptly.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Video task response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] }, "examples": { "cl25LastFrameSuccess": { "$ref": "#/components/examples/Seedance25LastFrameNormalizedSuccess" }, "success": { "summary": "Success response", "value": { "id": "task_xxx", "task_id": "task_xxx", "model": "seedance-2.0-kz-fast", "data": { "status": "succeeded", "task_id": "model_task_xxx", "duration": 5, "error": "", "video_url": "https://example.com/result.mp4", "usage": { "completion_tokens": 108900, "total_tokens": 108900 } }, "output": { "url": "https://example.com/result.mp4" }, "result_url": "https://example.com/result.mp4", "url": "https://example.com/result.mp4", "video_url": "https://example.com/result.mp4", "request_id": "2026060301010100000000000000000000", "trace_id": "2026060301010100000000000000000000" } }, "SGStandard1080PCompleted": { "$ref": "#/components/examples/SGStandard1080PCompleted" }, "SGStandard4KCompleted": { "$ref": "#/components/examples/SGStandard4KCompleted" } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/videos/{task_id}/cancel": { "post": { "tags": [ "Video Compatibility" ], "summary": "Cancel a video task", "operationId": "cancelVideoTask", "description": "Cancels an unfinished video task owned by the authenticated account. MoonApiX first marks the task as cancelled and refunds pre-consumed quota. If the selected model supports cancelling in-progress tasks, MoonApiX also attempts a best-effort stop request. Deleting a generated video or output asset is not the same as cancelling an in-progress generation task. SH models do not support this operation; a submitted SH task returns an explicit unsupported error and is not cancelled or refunded by this call.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task cancelled. Stopping the in-progress generation may be unsupported or best-effort.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCancelResponse" }, "examples": { "success": { "summary": "Local cancel with refund", "value": { "id": "task_01HX...", "object": "video", "status": "cancelled", "cancelled": true, "refund_requested": true, "trace_id": "2026060301010100000000000000000000", "request_id": "2026060301010100000000000000000000", "task_chain": [ { "step": "cancel", "status": "succeeded" }, { "step": "billing", "status": "refunded" }, { "step": "remote_cancel", "status": "skipped" } ], "remote_cancel": { "attempted": true, "supported": false, "succeeded": false, "error": "" } } } } } }, "headers": { "X-MoonApiX-Trace-Id": { "description": "MoonApiX request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonApiX request ID, usually the same as X-MoonApiX-Trace-Id.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Task not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Task already finished and cannot be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/videos/{task_id}/content": { "get": { "tags": [ "Video Compatibility" ], "summary": "Get video content", "operationId": "getVideoTaskContent", "description": "Fallback compatibility download endpoint for a succeeded video task. Prefer a usable result URL returned by the task query response. Use this endpoint only when the succeeded task does not expose a usable result URL; it may return 302 with a Location header or a proxied video stream.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Video stream fallback when no usable result URL is exposed by the succeeded task response.", "content": { "video/mp4": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Redirect to the generated video media URL.", "headers": { "Location": { "description": "Customer-usable generated video URL. It may be an approved direct media URL or a MoonApiX-managed URL.", "schema": { "type": "string", "format": "uri", "example": "https://media.example.com/generated/video/result.mp4" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/videos/{video_id}/remix": { "post": { "tags": [ "Video Compatibility" ], "summary": "Remix video task", "operationId": "remixVideoTask", "description": "Remix video task using MoonApiX video parameters. SH models do not support remix; this operation returns an explicit unsupported error without creating a remix task.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "textToVideo": { "summary": "Text to video", "value": { "model": "seedance-2.0-kz-fast", "prompt": "A cinematic product video with slow camera movement.", "duration": 5, "aspect_ratio": "16:9" } }, "firstLastFrame": { "summary": "First and last frame", "value": { "model": "sora-v3-fast", "prompt": "Create a smooth transition between the first and last frame.", "seconds": "5", "first_frame_url": "https://example.com/first-frame.jpg", "last_frame_url": "https://example.com/last-frame.jpg", "aspect_ratio": "16:9" } }, "contentItems": { "summary": "Multimedia content items", "value": { "model": "seedance-2.0-kz", "prompt": "Keep the character identity and generate a stage singing video.", "duration": 5, "ratio": "16:9", "resolution": "720p", "generate_audio": true, "content": [ { "type": "image_url", "image_url": { "url": "https://example.com/character.png" }, "role": "reference_image" }, { "type": "audio_url", "audio_url": { "url": "https://example.com/song.mp3" }, "role": "reference_audio" } ] } }, "moonapixAsset": { "summary": "Use explicit MoonApiX asset reference when supported", "value": { "model": "seedance-2.0-kz-fast", "prompt": "Animate the product with a slow rotating camera.", "image": "Asset://asset_xxx", "duration": 5 } } } } } }, "responses": { "200": { "description": "Created video task.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "$ref": "#/components/schemas/OpenAIVideoResponse" } ] }, "examples": { "success": { "summary": "Success response", "value": { "id": "video_456", "object": "video", "model": "sora-2", "status": "submitted", "progress": 0, "created_at": 1712698600, "size": "720x1280", "seconds": "8", "remixed_from_video_id": "video_123" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/web-reader/read": { "post": { "tags": [ "Web" ], "summary": "Read web page", "operationId": "readWebPage", "description": "Reads a web page and returns extracted content in the requested format.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebReaderRequest" }, "examples": { "basic": { "summary": "Read page", "value": { "url": "https://example.com/article", "format": "md", "liteMode": true } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "url": "https://www.chowtaifook.com/zh-hk/eshop/realtime-gold-price.html?srsltid=AfmBOoqKvz50IajJ5KCRR9sAjt9zHmAJRevTm1-V4rFcsYqSOu_GvUbk", "format": "md" } } } } } }, "responses": { "200": { "description": "Reader response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/web-search/search": { "post": { "tags": [ "Web" ], "summary": "Search web", "operationId": "searchWeb", "description": "Searches the web and returns results in the requested format.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebSearchRequest" }, "examples": { "basic": { "summary": "Search web", "value": { "query": "MoonApiX API documentation", "area": "global", "count": 10, "format": "json" } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "query": "Today's gold price", "area": "global", "freshness": "Week", "includeImages": false, "page": 1, "count": 5, "format": "json" } } } } } }, "responses": { "200": { "description": "Search response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" }, "examples": { "success": { "summary": "Success response", "value": { "id": "9d4b7513-77e5-481a-b015-48313946f33b", "prompt": "cat dance", "state": "pending", "created_at": "2024-07-01T07:35:13.49866Z", "video": null, "liked": null, "estimate_wait_seconds": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1beta/models/{modelName}:generateContent": { "post": { "tags": [ "Gemini" ], "summary": "Generate content", "operationId": "generateGeminiContent", "description": "Creates a Gemini-compatible content generation request.", "parameters": [ { "name": "modelName", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentRequest" }, "examples": { "basic": { "summary": "Generate content", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Write a short welcome message." } ] } ] } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Write a poem." } ] } ] } }, "imageGeneration": { "summary": "Gemini image generation", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Generate a clean product mockup on a white studio table." } ] } ] } } } } } }, "responses": { "200": { "description": "Generated content response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1beta/models/{model}:generateContent": { "post": { "tags": [ "Gemini" ], "summary": "Generate content", "operationId": "generateGeminiMediaContent", "description": "Creates a Gemini-compatible content generation request.", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "nano-banana-2" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeminiGenerateContentRequest" }, "examples": { "basic": { "summary": "Generate content", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Write a short welcome message." } ] } ] } }, "moonapixExample": { "summary": "MoonApiX example", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Tell me about this instrument" }, { "inlineData": { "mimeType": "image/jpeg", "data": "" } } ] } ] } }, "imageGeneration": { "summary": "Gemini image generation", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Generate a clean product mockup on a white studio table." } ] } ] } } } } } }, "responses": { "200": { "description": "Generated content response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericJsonResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/asset-groups": { "get": { "tags": [ "Assets" ], "summary": "List asset groups", "operationId": "listAssetGroups", "description": "Returns customer-defined asset groups for the authenticated account. Use group_id from this endpoint when uploading or querying assets.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional asset domain filter." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "enabled", "disabled" ] } } ], "responses": { "200": { "description": "Asset group list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetGroups" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Assets" ], "summary": "Create asset group", "operationId": "createAssetGroup", "description": "Creates a customer-defined asset group. Use the returned group_id when uploading assets, listing assets, or validating asset details.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "domain": { "type": "string" } }, "required": [ "name" ] }, "examples": { "createGroup": { "summary": "Create asset group", "value": { "name": "project-a", "description": "Project A materials", "domain": "media" } } } } } }, "responses": { "200": { "description": "Created asset group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/asset-groups/{group_id}": { "get": { "tags": [ "Assets" ], "summary": "Get asset group", "operationId": "getAssetGroup", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Asset group detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Asset group not found." } }, "description": "Returns one asset group. The group must belong to the authenticated account." }, "patch": { "tags": [ "Assets" ], "summary": "Update asset group", "operationId": "updateAssetGroup", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "examples": { "renameGroup": { "summary": "Rename asset group", "value": { "name": "project-a-updated", "description": "Updated materials" } } } } } }, "responses": { "200": { "description": "Updated asset group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetGroup" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Asset group not found." } }, "description": "Updates an asset group name or description. Send at least one field." }, "delete": { "tags": [ "Assets" ], "summary": "Soft-delete asset group", "operationId": "deleteAssetGroup", "description": "Soft-deletes a custom group owned by the authenticated account and returns the group object with status=disabled and deleted=true. Default and system groups are protected. A custom group can be soft-deleted while it contains assets. Member assets, their original group_id, and historical associations remain; assets are not deleted or moved. The operation does not remove OSS files or external certification records, and does not promise to revoke issued URLs or cancel existing tasks.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Soft-deleted group object with status=disabled and deleted=true.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AssetGroup" }, { "type": "object", "properties": { "status": { "const": "disabled" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "status", "deleted" ] } ] }, "example": { "object": "asset_group", "id": "group_xxx", "group_id": "group_xxx", "name": "project-a", "group_type": "custom", "status": "disabled", "deleted": true } } } }, "400": { "description": "Invalid group ID." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The group does not exist, belongs to another account, or is already disabled. Repeated deletion also returns 404; error code group_not_found." }, "409": { "description": "Default and system groups cannot be deleted; error code protected_group." } } } }, "/v1/assets/{asset_id}/archive": { "post": { "tags": [ "Assets" ], "summary": "Archive asset", "operationId": "archiveAsset", "x-release-status": "active", "description": "Active in the current MoonApiX asset API release. Archive an existing immutable content version independently of model preparation. Omit the body or send {} to reuse an available recorded source, provide one URL, or upload exactly one file. The bytes must match the established content baseline; a matching URL alone is not proof. Unknown/unverified historical content returns 409 until a verified source baseline exists. Storage failure does not invalidate a successful preparation binding. GET observes storage state; a new archive call may retry. ready confirms an accessible verified copy at the query time; retention follows the separate storage service contract.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "MoonApiX asset identity owned by the authenticated account." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetArchiveJSONRequest" }, "examples": { "existing": { "summary": "Reuse recorded source", "value": {} }, "source": { "summary": "Materialize matching content", "value": { "url": "https://example.com/reference.png" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AssetArchiveMultipartRequest" } } } }, "responses": { "200": { "description": "Verified managed copy ready; identity and preparation remain independent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetOperationResponse" }, "examples": { "result": { "summary": "Verified managed copy ready; identity and preparation remain independent.", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "status": "ready", "storage": { "status": "ready" } } } } } } }, "202": { "description": "Another archive operation is still processing; query the same asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetOperationResponse" }, "examples": { "result": { "summary": "Another archive operation is still processing; query the same asset.", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "status": "ready", "storage": { "status": "processing" } } } } } } }, "400": { "description": "Invalid or unavailable archive source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Asset not found or disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Content baseline unverified, supplied bytes differ, or archive operation conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Archive input exceeds the platform media size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Archive could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Storage could not be confirmed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/assets/{asset_id}/prepare": { "post": { "tags": [ "Assets" ], "summary": "Prepare asset for model use", "operationId": "prepareAsset", "x-release-status": "active", "description": "Active in the current MoonApiX asset API release. Explicitly prepare or resume an asset for one public model/current calling configuration. Normal scheduling chooses an execution path before existing preparation is inspected; this operation does not prefer a cheaper or already-ready path. Omit operation to reuse a current ready reference or advance an active attempt. create, rebuild and refresh are explicit operation options. Identity and storage status are independent and are not turned into failed states by preparation failure. Query detail with the same model to observe readiness; GET does not start or poll this work. Compatible models can reuse a valid prepared reference, but readiness is revalidated for the requested model. generation_ready=true is a permitted prepared-path existence result, not an immediate-generation guarantee.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "MoonApiX asset identity owned by the authenticated account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPrepareRequest" }, "examples": { "prepare": { "summary": "Prepare or resume current target model", "value": { "model": "seedance-2.5-cl" } } } } } }, "responses": { "200": { "description": "At least one permitted path is ready in the returned model scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPrepareResponse" }, "examples": { "result": { "summary": "At least one permitted path is ready in the returned model scope.", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "status": "ready", "storage": { "status": "ready" }, "preparation": { "model": "seedance-2.5-cl", "status": "ready", "generation_ready": true, "review_status": "unknown" } } } } } } }, "202": { "description": "Preparation accepted or still incomplete; observe and resume the same asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPrepareResponse" }, "examples": { "result": { "summary": "Preparation accepted or still incomplete; observe and resume the same asset.", "value": { "object": "asset", "asset_id": "asset_xxx", "asset_ref": "Asset://asset_xxx", "status": "ready", "storage": { "status": "ready" }, "preparation": { "model": "seedance-2.5-cl", "status": "processing", "generation_ready": false, "review_status": "unknown" } } } } } } }, "400": { "description": "Missing model, unavailable calling scope, unsupported operation, or non-empty config_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Asset not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Selected execution path, verified content or preparation is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Preparation state could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Preparation result could not be confirmed; retry the preparation operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/visual-validate-sessions": { "post": { "tags": [ "Identity Verification" ], "summary": "Create a visual liveness verification session", "operationId": "createVisualValidateSession", "description": "Creates a one-time verification session that expires after 30 minutes. Give the returned h5_link to the end user. Clients must poll POST /v1/visual-validate-results to read the status. callback_url is a required HTTPS callback parameter; verification status is confirmed through polling. Completion creates a private asset group and returns group_id, but does not create an asset_id. The group may initially be empty.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "callback_url" ], "properties": { "model": { "type": "string", "description": "Target model enabled for the current API key with an active route that supports liveness verification.", "example": "seedance-2.0-sz" }, "callback_url": { "type": "string", "format": "uri", "description": "Required HTTPS verification callback parameter. Clients must still poll the result endpoint.", "example": "https://client.example.com/visual-validate/callback" } } }, "examples": { "createSession": { "summary": "Create a liveness session", "value": { "model": "seedance-2.0-sz", "callback_url": "https://client.example.com/visual-validate/callback" } } } } } }, "responses": { "201": { "description": "Session created. Open h5_link on the end user's device.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "session_id", "h5_link", "expires_at" ], "properties": { "object": { "type": "string", "const": "visual_validate_session" }, "session_id": { "type": "string", "description": "Session ID returned by the create endpoint; it starts with vvs_.", "example": "vvs_0123456789abcdefghijklmnopqrstuvwxyzabcd" }, "h5_link": { "type": "string", "format": "uri", "description": "One-time, short-lived user-facing verification link." }, "expires_at": { "type": "integer", "format": "int64", "description": "Session expiration as a Unix timestamp in seconds." } } }, "examples": { "created": { "summary": "Session created", "value": { "object": "visual_validate_session", "session_id": "vvs_0123456789abcdefghijklmnopqrstuvwxyzabcd", "h5_link": "https://example.com/one-time-link", "expires_at": 1710001800 } } } } } }, "400": { "description": "Invalid JSON, missing model, or invalid HTTPS callback URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key cannot use the requested model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session ID or local group ID could not be generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The verification service failed to create the session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Session storage is unavailable or no active liveness-compatible route is available for the model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/visual-validate-results": { "post": { "tags": [ "Identity Verification" ], "summary": "Get a visual liveness verification result", "operationId": "getVisualValidateResult", "description": "Queries a session created by the current API user. Returns pending while verification is processing; when complete, returns a MoonApiX private asset group_id, not an asset_id. Repeated queries for a completed session return the same group_id. The group may initially be empty; upload media into it to create an asset_id. A completed result may also include upstream.group_id, the original official group ID registered for this session. Upload and management continue to use the top-level MoonApiX group_id. Pending responses have no asset group.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "description": "Session ID returned by the create endpoint; it starts with vvs_.", "example": "vvs_0123456789abcdefghijklmnopqrstuvwxyzabcd" } } }, "examples": { "pollResult": { "summary": "Poll a session result", "value": { "session_id": "vvs_0123456789abcdefghijklmnopqrstuvwxyzabcd" } } } } } }, "responses": { "200": { "description": "Session is pending or completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "session_id", "status" ], "properties": { "object": { "type": "string", "const": "visual_validate_result" }, "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed" ] }, "group_id": { "type": "string", "description": "MoonApiX private asset group ID, present when status is completed. This is not an asset ID." }, "upstream": { "type": "object", "additionalProperties": false, "description": "Official group identifier, available when verification has completed.", "properties": { "group_id": { "type": "string", "description": "Original official group ID registered for this completed session." } } } } }, "examples": { "pending": { "summary": "Verification is still processing", "value": { "object": "visual_validate_result", "session_id": "vvs_0123456789abcdefghijklmnopqrstuvwxyzabcd", "status": "pending" } }, "completed": { "summary": "Verification completed; group may be empty", "description": "Upload media to this group to create an asset_id.", "value": { "object": "visual_validate_result", "session_id": "vvs_0123456789abcdefghijklmnopqrstuvwxyzabcd", "status": "completed", "group_id": "group_xxx", "upstream": { "group_id": "group-official-example" } } } } } } }, "400": { "description": "Invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key cannot use the model associated with this session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The session ID is missing, malformed, unknown, expired, or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The verification route pinned to this session is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The completed result or verified asset group could not be persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The verification service failed to return a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Session storage or verification service configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/asset-groups/{group_id}/upstream": { "post": { "tags": [ "Assets" ], "operationId": "createOfficialAssetGroup", "summary": "Create an official Volcengine asset group", "description": "Create an official AIGC group for an existing enabled MoonApiX custom group. Uses the local group name and description. Save both the MoonApiX group ID and returned official group ID. If a group already exists, returns 200 without creating another one. An uncertain create outcome must be checked before resubmission.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group_example", "description": "MoonApiX group_id owned by the authenticated account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "minLength": 1, "description": "Public MoonApiX model." } } }, "examples": { "result": { "summary": "Example request", "value": { "model": "seedance-2.0-sz" } } } } } }, "responses": { "200": { "description": "Existing group relationship returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetGroupResponse" }, "examples": { "result": { "summary": "Existing group relationship returned.", "value": { "object": "asset_group", "group_id": "group_example", "upstream": { "group_id": "group-official-example" } } } } } } }, "201": { "description": "Official group created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetGroupResponse" }, "examples": { "result": { "summary": "Official group created.", "value": { "object": "asset_group", "group_id": "group_example", "upstream": { "group_id": "group-official-example" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Assets" ], "operationId": "getOfficialAssetGroup", "summary": "Read an official Volcengine asset group", "description": "Read official group details for the authenticated account. group_id remains the registered official ID; a differing latest official detail ID is returned separately as observed_group_id.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group_example", "description": "MoonApiX group_id owned by the authenticated account." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "example": "seedance-2.0-sz", "description": "Public MoonApiX model. Its asset scope must match the resource being managed." } ], "responses": { "200": { "description": "Official group detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetGroupResponse" }, "examples": { "result": { "summary": "Official group detail.", "value": { "object": "asset_group", "group_id": "group_example", "upstream": { "group_id": "group-official-example" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Assets" ], "operationId": "updateOfficialAssetGroup", "summary": "Update an official Volcengine asset group", "description": "Change the official group name and/or description. At least one update field is required. Does not edit the MoonApiX group. Detail reads may show the previous name for several minutes after success; re-query the same group rather than creating a new one.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group_example", "description": "MoonApiX group_id owned by the authenticated account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "minLength": 1, "description": "Public MoonApiX model." }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "maxLength": 300 } }, "anyOf": [ { "required": [ "name" ] }, { "required": [ "description" ] } ] }, "examples": { "result": { "summary": "Example request", "value": { "model": "seedance-2.0-sz", "name": "project-a-updated" } } } } } }, "responses": { "200": { "description": "Official group update accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetGroupResponse" }, "examples": { "result": { "summary": "Official group update accepted.", "value": { "object": "asset_group", "group_id": "group_example", "upstream": { "group_id": "group-official-example" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Assets" ], "operationId": "deleteOfficialAssetGroup", "summary": "Delete an official Volcengine asset group", "description": "Delete this account's empty official group, then remove its registered relationship. Delete official assets first; active preparations or remaining assets cause 409. Does not disable or delete the MoonApiX group. An uncertain delete can be retried on the same resource.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "group_example", "description": "MoonApiX group_id owned by the authenticated account." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "example": "seedance-2.0-sz", "description": "Public MoonApiX model. Its asset scope must match the resource being managed." } ], "responses": { "200": { "description": "Official group deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetGroupResponse" }, "examples": { "result": { "summary": "Official group deleted.", "value": { "object": "asset_group", "group_id": "group_example", "upstream": { "group_id": "group-official-example" }, "deleted": true } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/asset-groups/upstream": { "get": { "tags": [ "Assets" ], "operationId": "listOfficialAssetGroups", "summary": "List registered official asset groups", "description": "List only groups already registered to the authenticated account in the selected model asset scope. Does not import unregistered official resources. Uses offset/limit pagination.", "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "example": "seedance-2.0-sz", "description": "Public MoonApiX model. Its asset scope must match the resource being managed." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Registered official group summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetGroupList" }, "examples": { "result": { "summary": "Registered official group summaries.", "value": { "object": "list", "data": [ { "object": "asset_group", "group_id": "group_example", "upstream": { "group_id": "group-official-example" } } ], "total": 1, "offset": 0, "limit": 20 } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/assets/{asset_id}/upstream": { "post": { "tags": [ "Assets" ], "operationId": "prepareOfficialAsset", "summary": "Prepare or resume an official Volcengine asset", "description": "Explicitly prepare the existing MoonApiX asset for the selected public model, or advance the same active attempt. Equivalent to model preparation with additional official IDs when already available. 202 means processing; do not upload another copy. Re-read official detail for a current download URL. A valid existing official group relationship is required for independent group management.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "asset_example", "description": "MoonApiX asset_id owned by the authenticated account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string", "minLength": 1, "description": "Public MoonApiX model." }, "operation": { "type": "string", "enum": [ "create", "refresh", "rebuild" ], "description": "Normally omit to reuse a ready reference or advance the current attempt. Supported operations depend on the selected public model." } } }, "examples": { "result": { "summary": "Example request", "value": { "model": "seedance-2.0-sz" } } } } } }, "responses": { "200": { "description": "Prepared reference is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetPreparationResponse" }, "examples": { "result": { "summary": "Prepared reference is available.", "value": { "object": "asset", "asset_id": "asset_example", "asset_ref": "Asset://asset_example", "status": "ready", "storage": { "status": "ready" }, "upstream": { "asset_id": "asset-official-example", "group_id": "group-official-example", "status": "ready" }, "preparation": { "model": "seedance-2.0-sz", "status": "ready", "generation_ready": true, "review_status": "unknown" } } } } } } }, "202": { "description": "Preparation accepted or still processing; IDs may be absent until created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetPreparationResponse" }, "examples": { "result": { "summary": "Preparation accepted or still processing; IDs may be absent until created.", "value": { "object": "asset", "asset_id": "asset_example", "asset_ref": "Asset://asset_example", "status": "ready", "storage": { "status": "ready" }, "upstream": { "asset_id": "asset-official-example", "group_id": "group-official-example", "status": "ready" }, "preparation": { "model": "seedance-2.0-sz", "status": "processing", "generation_ready": false, "review_status": "unknown" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "Assets" ], "operationId": "getOfficialAsset", "summary": "Read official asset IDs and a media download URL", "description": "Return the original official asset ID, registered official group ID, latest observed group ID if different, and current official HTTPS media URL when available. The media URL may carry a short-lived signature; re-query detail to refresh. A rejected HEAD alone does not prove GET is unavailable: verify anonymous Range GET and media Content-Type. Do not send the MoonApiX API key to the media host.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "asset_example", "description": "MoonApiX asset_id owned by the authenticated account." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "example": "seedance-2.0-sz", "description": "Public MoonApiX model. Its asset scope must match the resource being managed." } ], "responses": { "200": { "description": "Official asset detail and current media URL, when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetResponse" }, "examples": { "result": { "summary": "Official asset detail and current media URL, when available.", "value": { "object": "asset", "asset_id": "asset_example", "asset_ref": "Asset://asset_example", "group_id": "group_example", "upstream": { "asset_id": "asset-official-example", "group_id": "group-official-example", "url": "https://media.example.test/reference.png", "status": "Active" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Assets" ], "operationId": "updateOfficialAsset", "summary": "Rename an official Volcengine asset", "description": "Change only the official asset name; description is not accepted. Does not rename the MoonApiX asset. The new name may take several minutes to appear in detail.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "asset_example", "description": "MoonApiX asset_id owned by the authenticated account." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "name" ], "properties": { "model": { "type": "string", "minLength": 1, "description": "Public MoonApiX model." }, "name": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "examples": { "result": { "summary": "Example request", "value": { "model": "seedance-2.0-sz", "name": "reference-updated" } } } } } }, "responses": { "200": { "description": "Official asset name update accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetResponse" }, "examples": { "result": { "summary": "Official asset name update accepted.", "value": { "object": "asset", "asset_id": "asset_example", "asset_ref": "Asset://asset_example", "group_id": "group_example", "upstream": { "asset_id": "asset-official-example", "group_id": "group-official-example", "name": "reference-updated" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Assets" ], "operationId": "deleteOfficialAsset", "summary": "Delete an official Volcengine asset", "description": "Delete this account's official asset and invalidate its prepared reference. Does not disable or delete the MoonApiX asset or stored media. Preparation in progress and shared resources are protected by 409. An uncertain delete may be retried on the same resource. Previously issued URLs need not expire immediately.", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "asset_example", "description": "MoonApiX asset_id owned by the authenticated account." }, { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "example": "seedance-2.0-sz", "description": "Public MoonApiX model. Its asset scope must match the resource being managed." } ], "responses": { "200": { "description": "Official asset deleted and ID resolution invalidated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetResponse" }, "examples": { "result": { "summary": "Official asset deleted and ID resolution invalidated.", "value": { "object": "asset", "asset_id": "asset_example", "group_id": "group_example", "deleted": true, "upstream": { "asset_id": "asset-official-example" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/assets/upstream": { "get": { "tags": [ "Assets" ], "operationId": "listOfficialAssets", "summary": "List registered official assets", "description": "List only the authenticated account's current registered assets in the selected model asset scope. Summary rows do not contain refreshed media download URLs; query official asset detail when downloading. Uses offset/limit pagination.", "parameters": [ { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "example": "seedance-2.0-sz", "description": "Public MoonApiX model. Its asset scope must match the resource being managed." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Registered official asset summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetList" }, "examples": { "result": { "summary": "Registered official asset summaries.", "value": { "object": "list", "data": [ { "object": "asset", "asset_id": "asset_example", "asset_ref": "Asset://asset_example", "group_id": "group_example", "upstream": { "asset_id": "asset-official-example", "group_id": "group-official-example", "status": "ready" } } ], "total": 1, "offset": 0, "limit": 20 } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v1/assets/resolve": { "post": { "tags": [ "Assets" ], "operationId": "resolveOfficialAssetIds", "summary": "Resolve official IDs to your MoonApiX asset or group", "description": "Provide model and at least one known official asset/group ID. Resolve only current resources owned by the authenticated account within the selected model asset scope. Does not import unknown resources or return a media URL. If both IDs are supplied they must refer to the same MoonApiX group. Use the registered group_id, not a differing observed_group_id. Group-only results use empty asset_id and asset_ref strings. Unknown or invalidated relationships return 404; ambiguity returns 409. Generation and management requests continue to use the returned MoonApiX IDs.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetResolveRequest" }, "examples": { "result": { "summary": "Example request", "value": { "model": "seedance-2.0-sz", "upstream_asset_id": "asset-official-example", "upstream_group_id": "group-official-example" } } } } } }, "responses": { "200": { "description": "Owned MoonApiX asset and/or group resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfficialAssetResolution" }, "examples": { "result": { "summary": "Owned MoonApiX asset and/or group resolved.", "value": { "object": "asset_resolution", "asset_id": "asset_example", "asset_ref": "Asset://asset_example", "group_id": "group_example", "upstream": { "asset_id": "asset-official-example", "group_id": "group-official-example" } } } } } } }, "400": { "description": "Invalid JSON, ID, public model, update fields or pagination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The API key does not permit the selected public model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource does not exist, is disabled, or does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The resource is unavailable, shared, being prepared or deleted; a group must be empty before deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The requested official resource operation could not be confirmed. Preserve the existing MoonApiX IDs and receipt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } } } }