{ "openapi": "3.1.0", "info": { "title": "cloudapi", "version": "1.1.0", "description": "Live service: https://cloudapi.site. Use the operator-provided gateway origin and a cloudapi-issued API key. Built on New API by QuantumNous. Read /llms-full.txt before invoking a paid operation." }, "servers": [ { "url": "https://cloudapi.site", "description": "CloudAPI production origin. Paths already include /v1; do not append a second /v1." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "models" }, { "name": "video" }, { "name": "image" }, { "name": "references" }, { "name": "tasks" } ], "paths": { "/v1/reference-uploads/policy": { "get": { "operationId": "getReferenceUploadPolicy", "tags": [ "references" ], "summary": "Get model-specific reference upload limits", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "query", "name": "model", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Caller upload policy: unlimited_file_size and limits keyed image/video/audio, each with available, max_bytes, size_disclosed. If size_disclosed is false, max_bytes is only the largest published limit and is not a universal published file limit. Current generation preflight selects compatible routes." } } } }, "/v1/reference-uploads/prepare": { "post": { "operationId": "prepareReferenceUpload", "tags": [ "references" ], "summary": "Authorize a direct private COS upload (no model generation)", "description": "Compute base64(MD5(file bytes)). POST metadata here, then PUT original file bytes to upload_url using exactly the returned headers, WITHOUT your CloudAPI Authorization header. The signed URL expires in 15 minutes, binds the exact byte count and checksum and forbids overwrite. Browsers set Content-Length automatically. Next call completeReferenceUpload. Reference upload metadata, completion and diagnostic calls have no local rate or daily quota. File-size specifications still follow the selected model. Reference files expire after 3 days; COS physical cleanup is asynchronous.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "content_type", "size", "content_md5" ], "properties": { "model": { "type": "string", "description": "Public model ID. Include this to follow its live reference file-size specification." }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "video/mp4", "video/webm", "audio/mpeg", "audio/wav" ] }, "size": { "type": "integer", "minimum": 1, "description": "Exact bytes. With model, query /v1/reference-uploads/policy?model=PUBLIC_ID first: disclosed byte limits are enforced; undisclosed is not claimed unlimited. Without model, legacy image 5 MiB / video-audio 10 MiB bounds apply." }, "content_md5": { "type": "string", "description": "Base64 of the 16-byte MD5 digest, not hexadecimal." } } } } } }, "responses": { "200": { "description": "Upload capability; keep private", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_url": { "type": "string" }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "upload_id": { "type": "string" }, "upload_expires_at": { "type": "integer" } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reference-uploads/complete": { "post": { "operationId": "completeReferenceUpload", "tags": [ "references" ], "summary": "Validate an uploaded file and obtain an owner-bound reference", "description": "Call with the upload_id after COS PUT succeeds. The gateway checks size, checksum, MIME and media signature. Put the returned url unchanged in images/videos/audios of your model request. This value is not a preview link; it expires in 3 days from upload authorization. It does not submit a generation task or charge model balance.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "upload_id" ], "properties": { "upload_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Validated reference", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "expires_at": { "type": "integer" } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "models" ], "summary": "List models available to this API token", "responses": { "200": { "description": "Intersect data[].id with /model-capabilities.json. A listed model is not a guarantee of current model availability.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "object": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "object": { "type": "string" } } } } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos": { "post": { "operationId": "createVideo", "tags": [ "video" ], "summary": "Create one asynchronous video task", "description": "Potentially billable. Require user authorization and an enabled model from listModels. No automatic fallback to a different model. Use the separate validateVideoSettings / validateImageSettings operation with the exact body before submitting. No dry-run flag is supported. Image requests can take up to 10 minutes; preserve the request key on timeout.", "x-openai-isConsequential": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "description": "Generate and persist a UUID for ONE intentional generation. Reuse the same key and identical body after connection loss. Never auto-generate a fresh key on retry. Scope is the user account; do not reuse across endpoints." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Seedance 2.0", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "auto", "720p" ], "default": "auto" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "auto", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Fast", "additionalProperties": false, "description": "Supports up to 9 reference images. Video and audio references are not supported. Face references may sometimes be blocked.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-fast" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 5, 10, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-fast", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Fast", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-fast-native" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-fast-native", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 9 reference images. Video and audio references are not supported. Face references may sometimes be blocked.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 30 reference images, 10 reference videos, 10 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5-native" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5-native", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 9 reference images. Video and audio references are not supported. Face references may sometimes be blocked.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5-welfare" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5-welfare", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 30, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Mini", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references. Include an image reference when using video or audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-mini-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p" ], "default": "480p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "allOf": [ { "if": { "anyOf": [ { "required": [ "videos" ], "properties": { "videos": { "minItems": 1 } } }, { "required": [ "audios" ], "properties": { "audios": { "minItems": 1 } } } ] }, "then": { "required": [ "images" ], "properties": { "images": { "minItems": 1 } } } } ], "examples": [ { "model": "seedance-2.0-mini-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "480p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Fast", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references. Include an image reference when using video or audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-fast-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p" ], "default": "480p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "allOf": [ { "if": { "anyOf": [ { "required": [ "videos" ], "properties": { "videos": { "minItems": 1 } } }, { "required": [ "audios" ], "properties": { "audios": { "minItems": 1 } } } ] }, "then": { "required": [ "images" ], "properties": { "images": { "minItems": 1 } } } } ], "examples": [ { "model": "seedance-2.0-fast-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "480p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 满血", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-full-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "480p", "1080p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-full-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 30 reference images, 10 reference videos, 10 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "21:9", "3:4", "4:3" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "480p", "1080p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Mini", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 audio references. Video references are not supported.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-mini-480p" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 5, 6, 7, 8, 9, 10, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "auto", "480p", "720p" ], "default": "auto" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-mini-480p", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "auto", "images": [] } ] }, { "type": "object", "title": "Video Upscale", "additionalProperties": false, "description": "Upscale one source video. 720p CNY 0.06/s, 1080p CNY 0.10/s, 2K CNY 0.24/s, 4K CNY 0.40/s. Billed by source video duration, rounded up. No prompt. MP4 only; maximum 128 MiB and 3600 seconds.", "required": [ "model", "videos" ], "properties": { "model": { "type": "string", "const": "video-upscale" }, "resolution": { "type": "string", "enum": [ "720p", "1080p", "2K", "4K" ], "default": "720p" }, "fps": { "type": "integer", "enum": [ 30, 60, 120, 240 ], "default": 30 }, "videos": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" } } }, "examples": [ { "model": "video-upscale", "resolution": "720p", "fps": 30, "videos": [ "https://example.com/source.mp4" ] } ] }, { "type": "object", "title": "MiniMax-H3", "additionalProperties": false, "description": "MiniMax-H3 discounted 768p video generation supports 1–15 seconds, 16:9 or 9:16 output, up to 9 images and 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "minimax-h3-special" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "768p" ], "default": "768p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "minimax-h3-special", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "768p", "images": [] } ] } ] } } } }, "responses": { "200": { "description": "Accepted video task or completed image response. Examples are illustrative, not real generation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "status": { "type": "string", "description": "For canonical polling use getTask, whose statuses are uppercase." } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/images/generations": { "post": { "operationId": "generateImage", "tags": [ "image" ], "summary": "Generate images and wait for the result", "description": "Potentially billable. Require user authorization and an enabled model from listModels. No automatic fallback to a different model. Use the separate validateVideoSettings / validateImageSettings operation with the exact body before submitting. No dry-run flag is supported. Image requests can take up to 10 minutes; preserve the request key on timeout.", "x-openai-isConsequential": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "description": "Generate and persist a UUID for ONE intentional generation. Reuse the same key and identical body after connection loss. Never auto-generate a fresh key on retry. Scope is the user account; do not reuse across endpoints." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Seedream 5 Pro", "additionalProperties": false, "description": "Native; 1K/2K output; Aspect ratios 16:9, 9:16, 1:1, 4:3, 3:4; Up to 8 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "seedream-5-pro" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "1K", "2K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 8, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedream-5-pro", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "16:9", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Midjourney", "additionalProperties": false, "description": "Native; Supports imagine, edits and blend; output dimensions are determined by the model; Aspect ratios 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9; Up to 10 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "midjourney" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "imagine", "edits", "blend" ], "default": "generate" }, "images": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "midjourney", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Midjourney Niji", "additionalProperties": false, "description": "Native; Supports imagine, edits and blend; output dimensions are determined by the model; Aspect ratios 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9; Up to 10 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "midjourney-niji" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "imagine", "edits", "blend" ], "default": "generate" }, "images": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "midjourney-niji", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "GPT Image 2", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 16:9, 9:16, 1:1, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gpt-image-2" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "3:2", "2:3" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gpt-image-2", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "16:9", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "GPT Image 2.5", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 1:1, 16:9, 9:16, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gpt-image-2.5" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gpt-image-2.5", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Gemini 3 Pro", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gemini-3-pro-image" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gemini-3-pro-image", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Gemini 3.1 Flash", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gemini-3.1-flash-image" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gemini-3.1-flash-image", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] } ] } } } }, "responses": { "200": { "description": "Accepted video task or completed image response. Examples are illustrative, not real generation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "created": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Opaque gateway URL. Download as returned without adding the API key. Expires within 24h, possibly earlier if source expires." }, "b64_json": { "type": "string" } } } } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "operationId": "getTask", "tags": [ "tasks" ], "summary": "Poll persisted task state (recommended every 5–10 seconds)", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use the exact id returned by createVideo." } ], "responses": { "200": { "description": "SUCCESS is terminal success; FAILURE is terminal failure. UNKNOWN is not success. Poll for a bounded time, then save the id for later; never submit a replacement automatically.", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "status" ], "properties": { "task_id": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string", "enum": [ "NOT_START", "SUBMITTED", "QUEUED", "IN_PROGRESS", "SUCCESS", "FAILURE", "UNKNOWN" ] }, "progress": { "type": "string", "example": "50%" }, "fail_reason": { "type": "string" }, "created_at": { "type": "integer" }, "finished_at": { "type": "integer" } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks/{task_id}/artifacts": { "get": { "operationId": "listTaskArtifacts", "tags": [ "tasks" ], "summary": "After SUCCESS, get original result file links", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use the exact id returned by createVideo." } ], "responses": { "200": { "description": "Download artifacts[].content_url exactly as returned. Signed URLs need no API key; never forward credentials to a media URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "artifacts" ], "properties": { "task_id": { "type": "string" }, "artifacts": { "type": "array", "items": { "type": "object", "required": [ "key", "type", "content_url" ], "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "mime_type": { "type": "string" }, "content_url": { "type": "string" }, "delivery": { "type": "string", "description": "Optional delivery hint; always use content_url exactly as returned." } } } } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/video-references": { "post": { "operationId": "uploadReference", "tags": [ "references" ], "summary": "Temporarily relay a local reference file without storing media on gateway disk", "description": "Prefer an existing HTTPS reference URL. For local files, prefer application/octet-stream with model and kind query parameters and original file bytes. JSON with raw Base64 (no data: prefix) remains supported. With COS enabled, returns an opaque reference valid for 3 days. Reference bytes are stored privately in COS; generated results use signed site download links. Use prepareReferenceUpload for direct upload without gateway bandwidth.", "x-openai-isConsequential": true, "parameters": [ { "name": "model", "in": "query", "description": "Required for binary upload; use the JSON field for JSON upload.", "schema": { "type": "string", "enum": [ "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-fast-native", "seedance-2.5", "seedance-2.5-native", "seedance-2.5-welfare", "seedance-2.0-mini-second", "seedance-2.0-fast-second", "seedance-2.0-full-second", "seedance-2.5-second", "seedream-5-pro", "midjourney", "midjourney-niji", "gpt-image-2", "gpt-image-2.5", "gemini-3-pro-image", "gemini-3.1-flash-image", "seedance-2.0-mini-480p", "video-upscale", "minimax-h3-special" ] } }, { "name": "kind", "in": "query", "description": "Required for binary upload; use the JSON field for JSON upload.", "schema": { "type": "string", "enum": [ "image", "video", "audio" ] } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Original PNG/JPEG <=5 MiB and <=40 MP, or MP4/WebM/MP3/WAV <=10 MiB. Requires model and kind query parameters." } }, "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "model", "kind", "data" ], "properties": { "model": { "type": "string", "enum": [ "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-fast-native", "seedance-2.5", "seedance-2.5-native", "seedance-2.5-welfare", "seedance-2.0-mini-second", "seedance-2.0-fast-second", "seedance-2.0-full-second", "seedance-2.5-second", "seedream-5-pro", "midjourney", "midjourney-niji", "gpt-image-2", "gpt-image-2.5", "gemini-3-pro-image", "gemini-3.1-flash-image", "seedance-2.0-mini-480p", "video-upscale", "minimax-h3-special" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio" ] }, "data": { "type": "string", "contentEncoding": "base64", "description": "PNG/JPEG <=5 MiB and <=40 MP; MP4/WebM/MP3/WAV <=10 MiB decoded. Entire JSON <=14 MiB." } } } } } }, "responses": { "200": { "description": "Put url unchanged in images/videos/audios. Owner-bound and valid for 3 days with COS enabled; not a preview/download URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "expires_at": { "type": "integer", "description": "Unix seconds" } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks/{task_id}/artifacts/{artifact_key}/content": { "get": { "operationId": "downloadTaskArtifact", "tags": [ "tasks" ], "security": [], "summary": "Open a previously returned signed result link", "description": "Only call when a file is needed. Never attach an API key. The link itself authorizes access; keep it private. The signed site link streams the file and supports GET, HEAD and supported Range requests. A failed download must not trigger generation.", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Use the exact id returned by createVideo." }, { "name": "artifact_key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "access", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Exact signature from content_url; do not compute or change it." }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Optional HTTP byte range, if supported by the source." } ], "responses": { "200": { "description": "Media bytes; inspect actual Content-Type.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial media bytes for a supported Range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/relay-media/{access}": { "get": { "operationId": "downloadImageResult", "tags": [ "tasks" ], "security": [], "summary": "Open a previously returned signed result link", "description": "Only call when a file is needed. Never attach an API key. The link itself authorizes access; keep it private. The signed site link streams the file and supports GET, HEAD and supported Range requests. A failed download must not trigger generation.", "parameters": [ { "name": "access", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Exact opaque segment from the image result url. Upload reference tokens cannot be downloaded." }, { "name": "Range", "in": "header", "schema": { "type": "string" }, "description": "Optional HTTP byte range, if supported by the source." } ], "responses": { "200": { "description": "Media bytes; inspect actual Content-Type.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "206": { "description": "Partial media bytes for a supported Range.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/validate": { "post": { "operationId": "validateVideoSettings", "tags": [ "video" ], "summary": "Check complete model settings without generation or billing", "description": "Send the exact generation JSON after references are ready. Checks token access, reference ownership, complete parameter compatibility and current availability. It never submits a generation task, reserves funds or consumes model balance. A successful check is not a reservation; actual submission checks availability again. Do not drop references or silently change explicit settings on failure.", "x-openai-isConsequential": false, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Seedance 2.0", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "auto", "720p" ], "default": "auto" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "auto", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Fast", "additionalProperties": false, "description": "Supports up to 9 reference images. Video and audio references are not supported. Face references may sometimes be blocked.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-fast" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 5, 10, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-fast", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Fast", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-fast-native" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-fast-native", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 9 reference images. Video and audio references are not supported. Face references may sometimes be blocked.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 30 reference images, 10 reference videos, 10 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5-native" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5-native", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 9 reference images. Video and audio references are not supported. Face references may sometimes be blocked.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5-welfare" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5-welfare", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 30, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Mini", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references. Include an image reference when using video or audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-mini-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p" ], "default": "480p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "allOf": [ { "if": { "anyOf": [ { "required": [ "videos" ], "properties": { "videos": { "minItems": 1 } } }, { "required": [ "audios" ], "properties": { "audios": { "minItems": 1 } } } ] }, "then": { "required": [ "images" ], "properties": { "images": { "minItems": 1 } } } } ], "examples": [ { "model": "seedance-2.0-mini-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "480p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Fast", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references. Include an image reference when using video or audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-fast-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "480p", "720p" ], "default": "480p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "allOf": [ { "if": { "anyOf": [ { "required": [ "videos" ], "properties": { "videos": { "minItems": 1 } } }, { "required": [ "audios" ], "properties": { "audios": { "minItems": 1 } } } ] }, "then": { "required": [ "images" ], "properties": { "images": { "minItems": 1 } } } } ], "examples": [ { "model": "seedance-2.0-fast-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "480p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 满血", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 reference videos, 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-full-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "480p", "1080p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-full-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.5", "additionalProperties": false, "description": "Supports up to 30 reference images, 10 reference videos, 10 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.5-second" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "21:9", "3:4", "4:3" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "720p", "480p", "1080p" ], "default": "720p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.5-second", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "720p", "images": [] } ] }, { "type": "object", "title": "Seedance 2.0 Mini", "additionalProperties": false, "description": "Supports up to 9 reference images, 3 audio references. Video references are not supported.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "seedance-2.0-mini-480p" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 5, 6, 7, 8, 9, 10, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "auto", "480p", "720p" ], "default": "auto" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedance-2.0-mini-480p", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "auto", "images": [] } ] }, { "type": "object", "title": "Video Upscale", "additionalProperties": false, "description": "Upscale one source video. 720p CNY 0.06/s, 1080p CNY 0.10/s, 2K CNY 0.24/s, 4K CNY 0.40/s. Billed by source video duration, rounded up. No prompt. MP4 only; maximum 128 MiB and 3600 seconds.", "required": [ "model", "videos" ], "properties": { "model": { "type": "string", "const": "video-upscale" }, "resolution": { "type": "string", "enum": [ "720p", "1080p", "2K", "4K" ], "default": "720p" }, "fps": { "type": "integer", "enum": [ 30, 60, 120, 240 ], "default": 30 }, "videos": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" } } }, "examples": [ { "model": "video-upscale", "resolution": "720p", "fps": 30, "videos": [ "https://example.com/source.mp4" ] } ] }, { "type": "object", "title": "MiniMax-H3", "additionalProperties": false, "description": "MiniMax-H3 discounted 768p video generation supports 1–15 seconds, 16:9 or 9:16 output, up to 9 images and 3 audio references.", "required": [ "model", "prompt", "seconds" ], "properties": { "model": { "type": "string", "const": "minimax-h3-special" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "seconds": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "description": "Whole seconds. This canonical contract uses seconds; do not send duration or size." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "768p" ], "default": "768p" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 3, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "minimax-h3-special", "prompt": "A paper boat floating on a calm lake at sunrise", "seconds": 15, "aspect_ratio": "16:9", "resolution": "768p", "images": [] } ] } ] } } } }, "responses": { "200": { "description": "Accepted video task or completed image response. Examples are illustrative, not real generation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "validation_only" ], "properties": { "available": { "type": "boolean", "const": true }, "validation_only": { "type": "boolean", "const": true } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/images/validate": { "post": { "operationId": "validateImageSettings", "tags": [ "image" ], "summary": "Check complete model settings without generation or billing", "description": "Send the exact generation JSON after references are ready. Checks token access, reference ownership, complete parameter compatibility and current availability. It never submits a generation task, reserves funds or consumes model balance. A successful check is not a reservation; actual submission checks availability again. Do not drop references or silently change explicit settings on failure.", "x-openai-isConsequential": false, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Seedream 5 Pro", "additionalProperties": false, "description": "Native; 1K/2K output; Aspect ratios 16:9, 9:16, 1:1, 4:3, 3:4; Up to 8 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "seedream-5-pro" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "1K", "2K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 8, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "seedream-5-pro", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "16:9", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Midjourney", "additionalProperties": false, "description": "Native; Supports imagine, edits and blend; output dimensions are determined by the model; Aspect ratios 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9; Up to 10 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "midjourney" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "imagine", "edits", "blend" ], "default": "generate" }, "images": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "midjourney", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Midjourney Niji", "additionalProperties": false, "description": "Native; Supports imagine, edits and blend; output dimensions are determined by the model; Aspect ratios 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9; Up to 10 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "midjourney-niji" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "imagine", "edits", "blend" ], "default": "generate" }, "images": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "midjourney-niji", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "GPT Image 2", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 16:9, 9:16, 1:1, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gpt-image-2" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "3:2", "2:3" ], "default": "16:9" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gpt-image-2", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "16:9", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "GPT Image 2.5", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 1:1, 16:9, 9:16, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gpt-image-2.5" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gpt-image-2.5", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Gemini 3 Pro", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gemini-3-pro-image" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gemini-3-pro-image", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] }, { "type": "object", "title": "Gemini 3.1 Flash", "additionalProperties": false, "description": "Native; 1K/2K/4K output; Aspect ratios 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3; Up to 9 reference images; References use HTTPS URLs; one generation task per request.", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "const": "gemini-3.1-flash-image" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 10000 }, "response_format": { "type": "string", "enum": [ "url" ], "default": "url" }, "output_format": { "type": "string", "enum": [ "jpeg", "png" ] }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" ], "default": "1:1" }, "resolution": { "type": "string", "enum": [ "1K", "2K", "4K" ], "default": "1K" }, "n": { "type": "integer", "const": 1, "default": 1 }, "action": { "type": "string", "enum": [ "generate" ], "default": "generate" }, "images": { "type": "array", "maxItems": 9, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "videos": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] }, "audios": { "type": "array", "maxItems": 0, "items": { "type": "string", "maxLength": 12000, "description": "An existing public HTTPS media URL, or the exact opaque /v1/cos-references/... (3 days) or legacy /v1/relay-media/... string from reference upload. Do not decode, alter, download or prefix an opaque reference. For local files, use prepareReferenceUpload and completeReferenceUpload to upload directly to COS.", "pattern": "^(https://[^\\s]+|/v1/(?:relay-media|cos-references)/[A-Za-z0-9_-]+)$" }, "default": [] } }, "examples": [ { "model": "gemini-3.1-flash-image", "prompt": "A paper boat floating on a calm lake at sunrise", "response_format": "url", "aspect_ratio": "1:1", "resolution": "1K", "images": [] } ] } ] } } } }, "responses": { "200": { "description": "Accepted video task or completed image response. Examples are illustrative, not real generation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "available", "validation_only" ], "properties": { "available": { "type": "boolean", "const": true }, "validation_only": { "type": "boolean", "const": true } } } } } }, "400": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Request failed. Read error.code/message; never create a new idempotency key to retry an uncertain submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Create a scoped API key in /keys. Use the complete cloudapi token including sk-. Do not use a login password or browser session. Never include it in URLs or generated output." } }, "schemas": { "Error": { "type": "object", "description": "Error shape varies by validation/auth layer. Always check HTTP status. Use the documented status and error code.", "properties": { "error": { "type": "object", "properties": { "code": { "type": [ "string", "integer" ] }, "type": { "type": "string" }, "message": { "type": "string" } } }, "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }