{ "openapi": "3.1.0", "info": { "title": "MoonNexAI API", "version": "0.1.0", "description": "MoonNexAI public API specification. Complete API reference. Check account model availability on MoonNexAI before use." }, "servers": [ { "url": "https://moonnexai.com", "description": "MoonNexAI API" } ], "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": "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": [ "moonnexai" ] } }, "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", "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" } }, "error": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "null" } ] }, "trace_id": { "type": "string", "description": "MoonNexAI request trace ID. Provide this value when asking MoonNexAI to troubleshoot a task." }, "request_id": { "type": "string", "description": "MoonNexAI 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 MoonNexAI-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", "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": "Original public URL provided by the customer." }, "url": { "type": "string", "format": "uri", "description": "Customer-usable URL. For mode=asset this is usually the source URL; for mode=oss or mode=both this may be a MoonNexAI OSS test URL with no long-term retention or availability guarantee." }, "oss_url": { "type": "string", "format": "uri", "description": "MoonNexAI OSS test URL when mode=oss or mode=both is used. Test use only; no long-term retention, URL lifetime, availability, or production storage SLA is guaranteed." }, "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": "Customer asset record status." }, "sync_status": { "type": "string", "enum": [ "created", "syncing", "ready", "failed" ], "description": "Asset reference preparation status." }, "preparation_status": { "type": "string", "enum": [ "created", "syncing", "ready", "failed", "disabled" ], "description": "Preparation status for using this asset in generation requests." }, "generation_ready": { "type": "boolean", "description": "Whether this asset is ready to be used immediately in generation requests. If false, retry later with the same Asset:// reference." }, "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": "MoonNexAI request ID." }, "trace_id": { "type": "string", "description": "MoonNexAI trace ID for troubleshooting." }, "review_status": { "type": "string", "enum": [ "succeeded", "pending", "failed", "unknown" ], "description": "Asset review result. succeeded means the asset review passed, but generation readiness still depends on preparation_status and generation_ready." }, "review_passed": { "type": "boolean", "description": "Whether the asset review passed. This does not by itself mean the asset is ready for generation." }, "sync_error": { "type": "string", "description": "Asset preparation or synchronization failure reason. Usually present when preparation_status is failed." } }, "required": [ "id", "object", "type" ], "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": { "page": { "type": "integer", "examples": [ 1 ] }, "page_size": { "type": "integer", "examples": [ 20 ] }, "total": { "type": "integer", "examples": [ 1 ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "required": [ "items" ] }, "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": "MoonNexAI-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": [ "moonnexai-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" ] }, "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 MoonNexAI 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": "Last frame image URL or Asset:// reference." }, "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 only 4 seconds, and seedance-2.5-nt 4-30 seconds. NT does not support -1." }, "frames": { "type": "integer", "description": "Optional frame-count duration for models that support it. Mutually exclusive with duration; model capability rules apply." }, "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." }, "aspect_ratio": { "type": "string", "examples": [ "16:9" ], "description": "MoonNexAI 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." }, "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.", "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. All four NT models support 720p only." }, "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." }, "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." }, "seed": { "type": "integer", "description": "Random seed. Omit or use -1 for a random result; a fixed seed only makes results similar, not frame-identical." }, "camera_fixed": { "type": "boolean", "description": "Whether to keep the camera fixed when supported by the selected model." }, "return_last_frame": { "type": "boolean", "default": false, "description": "Whether to return last-frame information when supported." }, "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." }, "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." }, "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." }, "draft": { "type": "boolean", "default": false, "description": "Create a draft task when the selected model exposes draft generation." }, "service_tier": { "type": "string", "default": "default", "description": "Requested service tier. Availability depends on the model and account." }, "execution_expires_after": { "type": "integer", "description": "Task execution expiration window in seconds. If omitted, the platform default is used." }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Optional model tools. Use only when the selected model explicitly supports them." }, "safety_identifier": { "type": "string", "description": "Optional safety-policy identifier. Do not put credentials or sensitive personal data here." }, "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 MoonNexAI 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." }, "callback_url": { "type": "string", "format": "uri" }, "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." }, "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 MoonNexAI 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.", "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.moonnexai.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 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-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; 4 seconds only. 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 only; 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." } } }, "additionalProperties": true, "required": [ "model" ], "anyOf": [ { "required": [ "prompt" ] }, { "required": [ "content" ] } ], "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" } ] } }, "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." }, "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 MoonNexAI OSS test URL. both creates both outputs for free. MoonNexAI 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_moonnexai_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 MoonNexAI-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 MoonNexAI-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": "MoonNexAI 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 MoonNexAI-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": "MoonNexAI asset ID." }, "asset-id": { "type": "string", "description": "MoonNexAI 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" ] }, "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." } }, "additionalProperties": true }, "OpenAIVideoResponse": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "task_xxx" ] }, "task_id": { "type": "string", "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" }, "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 MoonNexAI-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 MoonNexAI-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 MoonNexAI-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": "MoonNexAI request ID." }, "trace_id": { "type": "string", "description": "MoonNexAI 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. MoonNexAI cancellation and refund can succeed even when this extra stop attempt is unsupported.", "properties": { "attempted": { "type": "boolean", "description": "Whether MoonNexAI 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 MoonNexAI." }, "refund_requested": { "type": "boolean", "description": "Whether MoonNexAI requested a refund of pre-consumed quota." }, "remote_cancel": { "$ref": "#/components/schemas/RemoteCancelResult" }, "trace_id": { "type": "string", "description": "MoonNexAI request trace ID." }, "request_id": { "type": "string", "description": "MoonNexAI 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": "MoonNexAI request ID." }, "trace_id": { "type": "string", "description": "MoonNexAI 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 MoonNexAI 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, MoonNexAI OSS test URL, or Asset:// reference when supported by the selected model. MoonNexAI 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 MoonNexAI asset ID." }, "asset_ref": { "type": "string", "description": "Optional MoonNexAI 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": "MoonNexAI 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": "MoonNexAI 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": "MoonNexAI 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" } } } } } }, "examples": { "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" } } } }, "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" } }, "moonnexaiExample": { "summary": "MoonNexAI 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" } }, "moonnexaiExample": { "summary": "MoonNexAI 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" } }, "moonnexaiExample": { "summary": "MoonNexAI 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,..." ] } }, "moonnexaiExample": { "summary": "MoonNexAI 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,..." } }, "moonnexaiExample": { "summary": "MoonNexAI 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" } }, "moonnexaiExample": { "summary": "MoonNexAI 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,..." } }, "moonnexaiExample": { "summary": "MoonNexAI 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." } }, "moonnexaiExample": { "summary": "MoonNexAI 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" } }, "moonnexaiExample": { "summary": "MoonNexAI 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" ] } }, "moonnexaiExample": { "summary": "MoonNexAI 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 MoonNexAI 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" } }, "moonnexaiExample": { "summary": "MoonNexAI 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": { "get": { "tags": [ "Assets" ], "summary": "List assets", "operationId": "listAssets", "description": "Returns assets available to the authenticated account. Use group_id to list assets in one customer-defined group. Before using Asset:// references in generation requests, check status, preparation_status, and generation_ready.", "parameters": [ { "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", "page": 1, "page_size": 20, "total": 1, "items": [ { "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 } ] } } } } }, "headers": { "X-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-Trace-Id.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/assets/uploads": { "post": { "tags": [ "Assets" ], "summary": "Upload asset", "operationId": "uploadAsset", "description": "Explicitly create a reusable asset. OSS upload and asset authentication/preparation are free; later generation tasks are billed by their generation model. Customers should pass stable public media URLs from their own storage directly to production generation requests. mode=oss creates a MoonNexAI OSS URL for integration testing only; MoonNexAI does not guarantee long-term retention, URL lifetime, continued availability, or a production storage SLA. Use mode=asset when the selected model supports creating Asset:// references, including seedance-2.0-kz-fast, seedance-2.0-kz, 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.5-cl, seedance-2.0-gl, seedance-2.0-gl-fast, and seedance-2.0-gl-mini. For moon-2.0-am-720p-fast, prefer customer-owned public URLs; mode=oss is only a temporary testing aid. Seedance-2 model lines prepare assets independently; do not mix Asset:// IDs across KZ, CL, CL-B, and GL model lines unless the asset has been prepared and verified for the target model. Use mode=both only during testing when both an OSS test URL and an Asset:// reference are required. 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 seedance-2.5-cl, failed authenticated asset resolution returns an error and does not fall back to a public URL.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "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": "Upload mode. oss creates a free MoonNexAI OSS URL for testing only. asset performs free asset authentication/preparation and creates an Asset:// reference when supported. both creates both outputs for free and should be used only when both are required during testing." }, "group_id": { "type": "string", "description": "Asset group ID. If omitted, the default group is used." } }, "required": [ "file", "type" ] }, "examples": { "ossUpload": { "summary": "Create a MoonNexAI 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" } } } }, "application/json": { "schema": { "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": "Target model when mode=asset or mode=both needs model-specific asset preparation. For Seedance-2, create or verify assets against the model line you will use for generation. seedance-2.5-cl assets must be ready for that model; failed Asset:// resolution returns an error and is not silently converted to a public URL." }, "type": { "type": "string", "enum": [ "image", "audio", "video", "file" ] }, "purpose": { "type": "string", "examples": [ "video_reference" ] }, "mode": { "type": "string", "enum": [ "asset", "oss", "both" ], "description": "asset saves the source URL and performs free authentication/preparation for an Asset:// reference when supported. oss creates a free MoonNexAI OSS test URL with no long-term retention or availability guarantee. both creates both outputs for free and should be used only during testing. Production clients must provide their own anonymously accessible public URL." } }, "required": [ "type", "mode" ] }, "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": "Use mode=asset only when the model page says Asset:// creation is supported." }, "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": "Use the CL model name when the asset will be used with seedance-2.0-cl-fast, seedance-2.0-cl, or seedance-2.0-cl-mini. Do not mix this asset with the seedance-2.0-kz main model line unless it has been prepared and verified for that target model.", "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": "Use type=video and role=reference_video for video input. The resulting Asset:// reference can be passed as video_url, reference_video_url, or references[].url when ready.", "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": "Use the exact GL public model that will generate the video. Customer-owned stable public URLs are preferred; mode=asset prepares a reusable MoonNexAI asset reference without requiring OSS transfer.", "value": { "model": "seedance-2.0-gl-mini", "mode": "asset", "type": "image", "purpose": "video_reference", "url": "https://example.com/reference.png" } } } } } }, "responses": { "200": { "description": "Uploaded asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "examples": { "success": { "summary": "Success response", "value": { "id": "asset_xxx", "asset_id": "asset_xxx", "object": "asset", "type": "image", "asset_type": "image", "group_id": "group_xxx", "domain": "media", "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, "status": "ready", "sync_status": "syncing", "preparation_status": "syncing", "generation_ready": false, "visibility": "private", "created_at": 1710000000, "updated_at": 1710000000, "request_id": "2026060301010100000000000000000000", "trace_id": "2026060301010100000000000000000000", "review_status": "pending", "review_passed": false } } } } }, "headers": { "X-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-Trace-Id.", "schema": { "type": "string" } } } }, "400": { "description": "Unsupported asset creation or invalid upload request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/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. Check generation_ready before using an Asset:// reference in a generation request.", "parameters": [ { "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." } ], "responses": { "200": { "description": "Asset detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" }, "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 } } } } }, "headers": { "X-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-Trace-Id.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/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 MoonNexAI.", "voice": "alloy", "response_format": "mp3" } }, "moonnexaiExample": { "summary": "MoonNexAI 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": { "moonnexaiExample": { "summary": "MoonNexAI 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": { "moonnexaiExample": { "summary": "MoonNexAI 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 MoonNexAI.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "gpt-5.6-terra" ] }, "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": "gpt-5.6-terra", "messages": [ { "role": "user", "content": "Generate a short product tagline." } ] } }, "moonnexaiExample": { "summary": "MoonNexAI 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": "moonnexai-embedding", "input": "MoonNexAI developer documentation" } }, "moonnexaiExample": { "summary": "MoonNexAI 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": "moonnexai-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": { "moonnexaiExample": { "summary": "MoonNexAI 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 MoonNexAI 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-nex.windfimusic.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": { "moonnexaiExample": { "summary": "MoonNexAI 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": [ "moonnexai-claude" ] }, "max_tokens": { "type": "integer" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessage" } } }, "required": [ "model", "messages" ] }, "examples": { "basic": { "summary": "Create message", "value": { "model": "moonnexai-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 MoonNexAI 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": "gpt-5.6-terra", "object": "model", "owned_by": "moonnexai" }, { "id": "gpt-image-2", "object": "model", "owned_by": "moonnexai" }, { "id": "gemini-3.1-flash-image-preview", "object": "model", "owned_by": "moonnexai" }, { "id": "gemini-3-pro-image-preview", "object": "model", "owned_by": "moonnexai" }, { "id": "nano-banana-2", "object": "model", "owned_by": "moonnexai" }, { "id": "nano-banana-pro", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-kz-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-sz", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-sz-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-sz-mini", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.5-sz", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.5-cl", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-cl-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-cl", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-cl-mini", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-cl-b-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-cl-b-mini", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-gl", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-gl-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "seedance-2.0-gl-mini", "object": "model", "owned_by": "moonnexai" }, { "id": "doubao-seedance-2-0-260128", "object": "model", "owned_by": "moonnexai" }, { "id": "doubao-seedance-2-0-fast-260128", "object": "model", "owned_by": "moonnexai" }, { "id": "doubao-seedance-2-0-mini-260615", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-dj-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-b-720p-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-b-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-c-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-d-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-e-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-wc-f-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-gl-a-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-gl-a-720p-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.5-gl-a", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-ld-a", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-ld-b", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-am-720p-fast", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-il-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-me-a-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-me-b-720p", "object": "model", "owned_by": "moonnexai" }, { "id": "moon-2.0-me-a-fast", "object": "model", "owned_by": "moonnexai" } ] } } } } } }, "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": [ "gpt-5.6-terra" ] }, "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": "gpt-5.6-terra", "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": [ "gpt-5.6-terra-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": "gpt-5.6-terra-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-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-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 MoonNexAI 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", "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 MoonNexAI 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 } }, "moonnexaiAsset": { "summary": "Use explicit MoonNexAI 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 MoonNexAI 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 MoonNexAI 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" } } } } }, "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://moonnexai.com/v1/videos/task_xxx/content", "data": { "video_url": "https://moonnexai.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 MoonNexAI 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 MoonNexAI 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.moonnexai.com/api/videos/seedance-2-0-nt for model limits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "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" } } } } } }, "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. Check status and error before reading content.video_url or other result fields. 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" } } } }, "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 MoonNexAI 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. MoonNexAI 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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoCreateRequest" }, "examples": { "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" } ] } }, "moonnexaiAsset": { "summary": "Use explicit MoonNexAI 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 MoonNexAI 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 MoonNexAI 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" } } } } } }, "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-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-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 MoonNexAI 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" } ] } }, "moonnexaiAsset": { "summary": "Use explicit MoonNexAI 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. Some compatibility responses may omit top-level status; if so, read data.status. Check status first; read result URLs only when status is succeeded. Failed or unfinished responses may omit output and result URL fields. 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 MoonNexAI-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": { "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-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-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. MoonNexAI first marks the task as cancelled and refunds pre-consumed quota. If the selected model supports cancelling in-progress tasks, MoonNexAI 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.", "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-MoonNexAI-Trace-Id": { "description": "MoonNexAI request trace ID.", "schema": { "type": "string" } }, "X-Request-Id": { "description": "MoonNexAI request ID, usually the same as X-MoonNexAI-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 MoonNexAI-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 MoonNexAI 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" } ] } }, "moonnexaiAsset": { "summary": "Use explicit MoonNexAI 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 } }, "moonnexaiExample": { "summary": "MoonNexAI 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": "MoonNexAI API documentation", "area": "global", "count": 10, "format": "json" } }, "moonnexaiExample": { "summary": "MoonNexAI 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." } ] } ] } }, "moonnexaiExample": { "summary": "MoonNexAI 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." } ] } ] } }, "moonnexaiExample": { "summary": "MoonNexAI 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." } } } }