Quickstart
Ask sales for a customer API key. The key starts with mn_live_ and must be sent from your backend, not from a public browser client.
z-image-spicy; single-image editing uses qwen-image-edit-spicy. Both image routes are processed asynchronously through MuleRouter.moderation: "disabled" for regular overseas routes. For seedance-2.0-nsfw, the Ark route is forwarded with moderation: "skip" according to the provider document.mnt_task_. Use it for polling.creations[0].url as the generated asset URL.curl -X POST "https://seedance2.lol/ent/v2/img2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"template": "i2v_high_quality",
"images": ["https://example.com/first-frame.jpg"],
"prompt": "A cinematic short video with controlled camera movement.",
"duration": 5,
"resolution": "720p",
"moderation": "disabled"
}'
curl "https://seedance2.lol/ent/v2/tasks/mnt_task_xxxxxxxxx/creations" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx"
images, video_urls, audio_urls, and audio_url. Small data URIs can work for tests, but URL inputs avoid request body limits.Authentication
Every customer API request requires a customer key issued by the operator. Keep this key on your server. Do not expose it in frontend JavaScript, mobile apps, or public repositories.
Authorization: Token mn_live_xxxxxAuthorization: Bearer mn_live_xxxxx or x-api-key: mn_live_xxxxxUnified OpenAI / new-api video API
POST /v1/videos is the recommended integration for new customers. One endpoint covers text-to-video, image-to-video, head-tail frame generation, and multimodal reference generation. It uses the same customer key, quota balance, model pricing, task ownership checks, and failed-task refunds as the native /ent/v2 API.
POST /v1/videosGET /v1/videos/{video_id}GET /v1/videos/{video_id}/contentinput_reference for image-to-video. Multiple assets are intentionally not auto-detected because two images could mean either head-tail frames or two reference images. For those requests, set metadata.mode explicitly.Authorization: Bearer mn_live_xxxxx. The create endpoint accepts OpenAI-style multipart/form-data; JSON is also accepted. In multipart requests, metadata must be a valid JSON string.seedance-2.0-nsfw supports synchronized native audio. Send audio=true to enable it or audio=false for silent output. The default is false. This is a Minuit extension to the OpenAI-compatible video request and is forwarded upstream as generate_audio: true.curl -X POST "https://seedance2.lol/v1/videos" \
-H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxx" \
-F "model=seedance-2.0-nsfw" \
-F "prompt=A cinematic scene with controlled camera motion" \
-F "seconds=5" \
-F "size=1280x720" \
-F "audio=false"
curl -X POST "https://seedance2.lol/v1/videos" \
-H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxx" \
-F "model=seedance-2.0-nsfw" \
-F "prompt=Animate the first frame with controlled cinematic motion" \
-F "input_reference=@first-frame.jpg" \
-F "seconds=5" \
-F "size=1280x720" \
-F "audio=true"
curl -X POST "https://seedance2.lol/v1/videos" \
-H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxx" \
-F "model=seedance-2.0-nsfw" \
-F "prompt=Create a smooth cinematic transition from the first frame to the last frame" \
-F 'metadata={"mode":"headtail2video","images":["https://example.com/first.jpg","https://example.com/last.jpg"]}' \
-F "seconds=5" \
-F "size=1280x720" \
-F "audio=false"
curl -X POST "https://seedance2.lol/v1/videos" \
-H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxx" \
-F "model=seedance-2.0-nsfw" \
-F "prompt=Use @1 for character identity and follow the referenced motion and audio" \
-F 'metadata={"mode":"reference2video","images":["https://example.com/character.jpg"],"video_urls":["https://example.com/motion.mp4"],"audio_urls":["https://example.com/voice.mp3"]}' \
-F "seconds=5" \
-F "size=1280x720" \
-F "audio=true"
curl "https://seedance2.lol/v1/videos/mnt_task_xxxxxxxxx" \
-H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxx"
curl -L "https://seedance2.lol/v1/videos/mnt_task_xxxxxxxxx/content" \
-H "Authorization: Bearer mn_live_xxxxxxxxxxxxxxxxx" \
-o result.mp4
| Field | Type | Required | Description |
|---|---|---|---|
model | string | No | Public model name. Defaults to the gateway's current video model. |
prompt | string | Yes | One complete prompt. Line breaks do not create multiple tasks. |
input_reference | file or string | No | One uploaded image, data URI, or HTTPS image URL. If supplied without a mode, the request is routed to image-to-video. |
seconds | number | No | Requested output duration. Defaults to 5 seconds; model-specific limits still apply. |
size | string | No | OpenAI-style dimensions such as 1280x720 or 720x1280. The gateway derives resolution and aspect ratio from this value. |
audio | boolean | No | Minuit extension for seedance-2.0-nsfw. Send true for synchronized native audio or false for silent output. Defaults to false. |
metadata | JSON object or JSON string | No | Advanced routing and reference assets. In multipart requests, send it as a JSON string. |
metadata.mode | string | For advanced modes | headtail2video for exactly two ordered images, or reference2video for multimodal references. |
metadata.images | string[] | Mode-specific | Ordered HTTPS image URLs. Head-tail mode requires exactly two. Reference mode accepts one or more. |
metadata.video_urls | string[] | No | Optional reference videos for reference2video. |
metadata.audio_urls | string[] | No | Optional reference audio for reference2video. Reference mode still requires at least one image or video. |
first_frame, last_frame, reference_image, reference_video, and reference_audio. Customers do not need to construct the upstream request body or supply upstream credentials.seedance-2.0-nsfw. The gateway applies the configured upstream moderation strategy server-side./ent/v2/text2video, /ent/v2/img2video, /ent/v2/reference2video, and /ent/v2/headtail2video endpoints remain available for existing integrations.Models and limits
Use the model and template names below. Internal routing, overseas upstream calls, and credentials are handled by the Minuit API gateway.
wan3.0-video accepts up to 20,000 characters, seedance-2.0-nsfw accepts up to 7,000 characters, and Wan 2.7 plus the available *_high_quality image/reference templates accept up to 5,000 characters. Longer prompts are truncated by the gateway before they are sent upstream.| Template | Best for | Public endpoint | Notes |
|---|---|---|---|
i2v_high_quality |
Image-to-video generation from one first-frame image. | /img2video |
Send this value in the template field, with one image in images. |
seedance-2.0-nsfw |
BytePlus Ark Seedance 2.0 NSFW-enabled route for API/SDK usage. Supports text, image reference, video reference, and head-tail frame inputs through the unified content format. |
/text2video, /img2video, /reference2video, /headtail2video |
Send this value in the model field. The gateway injects the private Ark API key and the configured ep-... endpoint. Aliases sd2.0-nsfw and sd20-nsfw are accepted. Billing is 28 / 60 / 150 credits per second for 480p / 720p / 1080p. |
wan2.7-spyciylv |
Alibaba Cloud Model Studio Wan 2.7 for prompt-only, first-frame, head-tail, and multi-reference video generation. | /text2video, /img2video, /reference2video, /headtail2video |
Send this public name in the model field. The gateway maps it to wan2.7-t2v, wan2.7-i2v, or wan2.7-r2v. Supports 720p / 1080p and 2-15 seconds. Reference requests containing video are limited to 10 seconds. The gateway also injects the upstream data-inspection override. |
wan3.0-video |
Alibaba Cloud Model Studio Wan 3.0 all-in-one text, first-frame, head-tail, and multi-reference video generation with native audio. | /text2video, /img2video, /reference2video, /headtail2video |
Send the exact model ID in the model field. Supports 480p / 720p / 1080p, adaptive or fixed aspect ratios, audio on/off, and 2-30 seconds. The upstream model is currently an invitational preview and must be enabled for the configured Model Studio workspace. |
z-image-spicy |
Spicy text-to-image generation from a prompt. | /text2image, /text2img |
Supports width and height from 256 to 1536 pixels, optional seed, and prompt_extend. Routed directly to MuleRouter. |
qwen-image-edit-spicy |
Spicy single-image editing using a source image and prompt. | /image2image, /reference2image |
Accepts one image URL or Base64 image in image, plus an optional seed. Routed directly to MuleRouter. |
qwen-image-3.0-pro |
Alibaba Cloud Model Studio Image 3 text-to-image and image editing with 1-3 reference images. | /text2image, /image2image, /reference2image |
Asynchronous gateway task backed by Model Studio. Supports 1-6 outputs, automatic sizing or 512-2048 pixel dimensions, optional negative prompt and seed. Image links are temporary upstream URLs. |
r2v_high_quality |
Reference-driven video generation from reference images and optional reference videos. | /reference2video |
Use reference images with optional video references for controlled generation. |
headtail_high_quality |
Head-tail frame video generation from exactly 2 images. | /headtail2video |
Use when you need the first frame and last frame to be controlled explicitly. |
wan2.7-spyciylv, wan3.0-video, and qwen-image-3.0-pro, the Minuit gateway automatically sends X-DashScope-DataInspection: {"input":"disable","output":"disable"} to Alibaba Cloud Model Studio. Do not send this upstream-only header in your Minuit API request.wan3.0-video supports 2-30 seconds. Default duration is 5 seconds.480p, 720p, and 1080p where available. Q-series NS routes support 720p and 1080p.mnt_task_... through the customer API. Poll /ent/v2/tasks/{task_id}/creations until state becomes success.Text to Video
Create a video directly from a text prompt using an available Seedance or Wan model.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | No | Use seedance-2.0-nsfw, wan3.0-video, or wan2.7-spyciylv. If omitted, the gateway defaults to wan3.0-video. |
prompt | string | Yes | Video prompt with subject, action, camera, style, lighting, and timing. |
resolution | string | No | 480p, 720p, or 1080p. Defaults to 720p. |
aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive. |
duration | number | No | Regular routes support up to 15 seconds. wan3.0-video supports 2-30 seconds and also accepts -1 for smart duration. |
audio | boolean | No | Optional native audio switch. Defaults to false; send true only when audio is needed. |
callback_url | string | No | Optional webhook URL for task state updates. |
moderation | string | Yes | Regular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream. |
curl -X POST "https://seedance2.lol/ent/v2/text2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-nsfw",
"prompt": "A cinematic character-driven video with smooth camera movement and realistic lighting.",
"resolution": "720p",
"aspect_ratio": "16:9",
"duration": 5,
"audio": false,
"moderation": "skip"
}'
curl -X POST "https://seedance2.lol/ent/v2/text2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-spyciylv",
"prompt": "A cinematic city scene with natural motion and synchronized atmosphere.",
"resolution": "720p",
"aspect_ratio": "9:16",
"duration": 5,
"prompt_extend": true
}'
curl -X POST "https://seedance2.lol/ent/v2/text2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"prompt": "A cinematic city story with natural dialogue, ambient sound, and smooth camera movement.",
"resolution": "720p",
"aspect_ratio": "9:16",
"duration": 15,
"audio": true,
"prompt_extend": true
}'
X-DashScope-DataInspection only when it calls Model Studio. API clients must not send or manage the upstream header.Text to Image
Create an image from text with z-image-spicy or Alibaba Cloud Image 3 qwen-image-3.0-pro. Both use asynchronous tasks. Store the task ID and poll for completed images.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | No | Use z-image-spicy or qwen-image-3.0-pro. The default is z-image-spicy. |
prompt | string | Yes | Image prompt with subject, style, composition, lighting, and detail requirements. |
width | integer | No | Output width from 256 to 1536 pixels. Defaults to 1024. |
height | integer | No | Output height from 256 to 1536 pixels. Defaults to 1536. |
aspect_ratio | string | No | Convenience alternative to width/height. The gateway maps common ratios such as 16:9, 9:16, 1:1, 3:4, and 2:3 to valid dimensions. |
seed | number/null | No | Optional random seed. Omit it for automatic seed selection. |
prompt_extend | boolean | No | Enable prompt expansion. Defaults to true. |
n | integer | No | Image 3 only: number of images, 1-6. Each output is billed separately. |
negative_prompt | string | No | Image 3 only: describe content to avoid. |
curl -X POST "https://seedance2.lol/ent/v2/text2image" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: image-request-unique-001" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-3.0-pro",
"prompt": "A polished product photograph with cinematic studio lighting.",
"width": 1536,
"height": 1024,
"n": 1,
"prompt_extend": true
}'
curl -X POST "https://seedance2.lol/ent/v2/text2image" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "z-image-spicy",
"prompt": "A cinematic, high-detail spicy editorial image with soft studio lighting.",
"width": 1024,
"height": 1536,
"prompt_extend": true,
"seed": null
}'
202 returns task_id, request_id, state: queueing and reserved quota before generation finishes. Poll GET /ent/v2/tasks/{task_id}/creations every 4-10 seconds with the same API key. On success, creations[].url contains the upstream image URLs. Definite failures refund credits.Idempotency-Key header, or request_id in the JSON body (1-128 letters, digits, dots, colons, underscores or hyphens). Reuse the same ID and identical generation parameters when retrying a lost response; this returns the original task without another charge. Reusing an ID with different parameters returns 409. Use a new ID only for an intentional new generation. This protection applies to Image 3 v2 routes, not other providers or legacy synchronous endpoints.curl "https://seedance2.lol/ent/v2/image-requests/image-request-unique-001" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx"
# Then poll the returned task_id:
curl "https://seedance2.lol/ent/v2/tasks/mni_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/creations" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx"
status: unknown with debug.requires_review: true means the upstream result could not be confirmed; contact support with the task/request ID. The gateway does not automatically repeat billable upstream requests. Debug includes stage, elapsed seconds and the upstream HTTP status when available.Image Edit
Edit an image with qwen-image-edit-spicy, or use qwen-image-3.0-pro with 1-3 reference images through Alibaba Cloud Model Studio.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | No | Use qwen-image-edit-spicy or qwen-image-3.0-pro. |
image | string | Yes | Source image URL or base64 image data URI to edit. |
images | array | No | Alternative input. Image 3 accepts 1-3 image URLs or Base64 data URIs; qwen-image-edit-spicy uses the first image. |
prompt | string | Yes | Text instruction describing the edit, such as changing background, adding/removing elements, or applying a style. |
seed | number/null | No | Optional random seed. Omit it for random generation. |
curl -X POST "https://seedance2.lol/ent/v2/image2image" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: image-edit-unique-001" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-3.0-pro",
"images": [
"https://example.com/reference-1.png",
"https://example.com/reference-2.png"
],
"prompt": "Keep the product identity and place it in a premium studio setting.",
"n": 1,
"prompt_extend": true
}'
202 returns a task ID immediately after enqueueing. Poll the creations endpoint for state: success and creations[].url. Output files remain upstream; we store only their URLs. Download promptly because upstream links can expire.curl -X POST "https://seedance2.lol/ent/v2/image2image" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-edit-spicy",
"image": "https://example.com/source.png",
"prompt": "Change the background to a warm cinematic studio scene while preserving the main subject.",
"seed": null
}'
qwen-image-edit-spicy uses one source image. Image 3 accepts 1-3 images. Both v2 routes return asynchronous tasks. The legacy /ent/v1/images/generations and /ent/v1/images/edits routes retain their synchronous behavior; migrate Image 3 integrations to v2 to avoid long client connections.Image to Video
Create a video from a first-frame image and a prompt. Prefer HTTPS image URLs for production traffic. Base64 data URIs can work for small tests, but URLs are more reliable for large assets.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
template | string | No | Use i2v_high_quality for the first-frame template path. If template is present, it takes priority over regular model routing. |
model | string | No | Optional model selector. Supported regular routes include seedance-2.0-nsfw, wan3.0-video, and wan2.7-spyciylv. |
images | array | Yes | One image URL or image data URI. The image is used as the first frame. |
image | string | No | Alternative single-image field. Use either images or image. |
prompt | string | Yes | Video direction, camera movement, style, timing, and scene details. |
resolution | string | No | 480p, 720p, or 1080p. Defaults to 720p. |
duration | number | No | 4 to 15 seconds for template routing. Default is 5. |
aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive. |
audio | boolean | No | Optional native audio switch. Defaults to false. |
moderation | string | Yes | Regular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream. |
callback_url | string | No | Optional webhook URL for task state updates. |
curl -X POST "https://seedance2.lol/ent/v2/img2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"template": "i2v_high_quality",
"images": ["https://example.com/client-owned-first-frame.jpg"],
"prompt": "A premium cinematic shot. Slow push-in, realistic lighting, clean skin texture, stable character identity.",
"resolution": "720p",
"aspect_ratio": "16:9",
"duration": 5,
"audio": false,
"moderation": "disabled"
}'
curl -X POST "https://seedance2.lol/ent/v2/img2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-nsfw",
"image": "https://example.com/source.jpg",
"prompt": "Animate the reference image with smooth cinematic motion.",
"resolution": "720p",
"aspect_ratio": "16:9",
"duration": 5,
"audio": false,
"moderation": "skip"
}'
curl -X POST "https://seedance2.lol/ent/v2/img2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-spyciylv",
"images": ["https://example.com/first-frame.jpg"],
"prompt": "A cinematic camera push-in with natural subject motion.",
"duration": 5,
"resolution": "720p",
"prompt_extend": true
}'
aspect_ratio field is used for text-to-video and reference generation when no first frame controls the output ratio. Wan 2.7 automatically generates matching audio unless an explicit audio_url is supplied.curl -X POST "https://seedance2.lol/ent/v2/img2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"images": ["https://example.com/first-frame.jpg"],
"prompt": "A cinematic camera push-in with natural movement and synchronized ambience.",
"duration": 15,
"resolution": "1080p",
"aspect_ratio": "adaptive",
"audio": true
}'
Reference Generation
Create a video from a prompt plus reference images or reference videos. When multiple images are provided, define characters or style references in the prompt by image order, for example @1 for the first image and @2 for the second image.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
template | string | No | Use r2v_high_quality for template routing, or omit it and set model to wan3.0-video or wan2.7-spyciylv. |
images | array | Yes | Reference images. Supported formats: png, jpeg, jpg, webp. |
prompt | string | Yes | Prompt text. Use @1, @2, etc. to refer to image order. |
video_urls | array | No | Optional video references. Supports up to 3 MP4 or MOV URLs. |
resolution | string | No | 480p, 720p, or 1080p. Defaults to 720p. |
aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, or 3:4. Defaults to 16:9. |
duration | number | No | Regular routes support up to 15 seconds. wan3.0-video supports up to 30 seconds, subject to the 30-second combined input/output video limit. |
audio | boolean | No | Optional native audio switch. Defaults to false. |
callback_url | string | No | Optional webhook URL for task state updates. |
moderation | string | Yes | Regular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream. |
curl -X POST "https://seedance2.lol/ent/v2/reference2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0-nsfw",
"images": [
"https://example.com/reference-image.jpg"
],
"video_urls": [
"https://example.com/reference-motion.mp4"
],
"prompt": "Use the reference video for motion and the reference image for identity and style.",
"aspect_ratio": "16:9",
"resolution": "720p",
"duration": 5,
"audio": false,
"moderation": "skip"
}'
curl -X POST "https://seedance2.lol/ent/v2/reference2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"template": "r2v_high_quality",
"images": [
"https://example.com/character-1.jpg",
"https://example.com/character-2.jpg"
],
"prompt": "@1 and @2 walk through a cinematic studio scene with stable identity and soft lighting.",
"aspect_ratio": "16:9",
"resolution": "720p",
"duration": 5,
"audio": false,
"moderation": "disabled"
}'
curl -X POST "https://seedance2.lol/ent/v2/reference2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"template": "r2v_high_quality",
"images": [
"https://example.com/character-1.jpg"
],
"video_urls": [
"https://example.com/reference-motion.mp4"
],
"prompt": "Use the reference video for motion rhythm and create a cinematic 5-second output with stable style.",
"aspect_ratio": "16:9",
"resolution": "720p",
"duration": 5,
"audio": false,
"moderation": "disabled"
}'
curl -X POST "https://seedance2.lol/ent/v2/reference2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-spyciylv",
"images": ["https://example.com/character.jpg"],
"video_urls": ["https://example.com/motion-reference.mp4"],
"prompt": "Use Image 1 for identity and Video 1 for movement.",
"aspect_ratio": "16:9",
"resolution": "720p",
"duration": 5
}'
curl -X POST "https://seedance2.lol/ent/v2/reference2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"images": ["https://example.com/character.jpg"],
"video_urls": ["https://example.com/motion-reference.mp4"],
"audio_urls": ["https://example.com/voice-reference.mp3"],
"prompt": "Use Image 1 for identity, Video 1 for movement, and Audio 1 for voice.",
"aspect_ratio": "adaptive",
"resolution": "720p",
"duration": 15,
"audio": true
}'
Head-tail Frame Video
Create a video from a first frame and a last frame. Send exactly two images: the first item is the starting frame, and the second item is the ending frame.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
template | string | No | Use headtail_high_quality for template routing, or omit it and set model to wan3.0-video or wan2.7-spyciylv. |
images | array | Yes | Exactly two images. images[0] is the first frame; images[1] is the last frame. |
prompt | string | Yes | Prompt describing the motion, transition, camera, and visual style between the two frames. |
video_urls | array | No | Optional reference videos. 0 to 3 items. |
audio_urls | array | No | Optional reference audio files. 0 to 3 items. |
resolution | string | No | 480p, 720p, or 1080p. Defaults to 720p. |
aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive. |
duration | number | No | Regular routes support up to 15 seconds. wan3.0-video supports 2-30 seconds and smart duration with -1. |
audio | boolean | No | Optional native audio switch. Defaults to false; send true only when audio is needed. |
callback_url | string | No | Optional webhook URL for task state updates. |
moderation | string | Yes | Regular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream. |
curl -X POST "https://seedance2.lol/ent/v2/headtail2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"template": "headtail_high_quality",
"images": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"prompt": "Create a smooth cinematic transition from the first frame to the last frame with stable identity and realistic motion.",
"aspect_ratio": "16:9",
"resolution": "720p",
"duration": 5,
"audio": false,
"moderation": "disabled"
}'
curl -X POST "https://seedance2.lol/ent/v2/headtail2video" \
-H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-spyciylv",
"images": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"prompt": "Create a smooth cinematic transition between the first and last frames.",
"resolution": "720p",
"duration": 5,
"prompt_extend": true
}'
wan2.7-i2v with first-frame and last-frame media roles, and automatically injects the Model Studio data-inspection override.Task polling
Task creation is asynchronous. Store the returned task id and poll the creations endpoint until the task reaches success or failed.
const API_BASE = "https://seedance2.lol";
const API_KEY = process.env.SPICY_VIDEO_API_KEY;
async function createImageToVideoTask() {
const response = await fetch(`${API_BASE}/ent/v2/img2video`, {
method: "POST",
headers: {
"Authorization": `Token ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
template: "i2v_high_quality",
images: ["https://example.com/first-frame.jpg"],
prompt: "Cinematic video, realistic motion, controlled camera movement.",
duration: 5,
resolution: "720p",
moderation: "disabled"
})
});
if (!response.ok) throw new Error(await response.text());
return response.json();
}
async function pollTask(taskId) {
while (true) {
const response = await fetch(`${API_BASE}/ent/v2/tasks/${taskId}/creations`, {
headers: { "Authorization": `Token ${API_KEY}` }
});
const task = await response.json();
if (task.state === "success") return task.creations;
if (task.state === "failed") throw new Error(task.err_msg || "Generation failed");
await new Promise((resolve) => setTimeout(resolve, 7000));
}
}
Pricing reference
The table below shows standard base credits. Video tasks calculate base credits as rate_per_second * duration. A customer billing percentage of 100 means standard price, while 80 means 80% of standard price (20% off). The gateway atomically charges ceil(base_credits * billing_percent / 100), with a minimum charge of 1 credit. Commercial reference pricing uses 1 credit = $0.005.
| Workflow | Resolution | Credits | Base USD reference | 40,000 credits can generate |
|---|---|---|---|---|
i2v_high_quality / r2v_high_quality / headtail_high_quality | 480p | 16 credits per second | $0.080 / second | 2,500 seconds, about 41.7 minutes |
i2v_high_quality / r2v_high_quality / headtail_high_quality | 720p | 34 credits per second | $0.170 / second | 1,176 seconds, about 19.6 minutes |
i2v_high_quality / r2v_high_quality / headtail_high_quality | 1080p | 85 credits per second | $0.425 / second | 470 seconds, about 7.8 minutes |
seedance-2.0-nsfw | 480p | 28 credits per second | $0.140 / second | 1,428 seconds, about 23.8 minutes |
seedance-2.0-nsfw | 720p | 60 credits per second | $0.300 / second | 666 seconds, about 11.1 minutes |
seedance-2.0-nsfw | 1080p | 150 credits per second | $0.750 / second | 266 seconds, about 4.4 minutes |
wan2.7-spyciylv | 720p | 20 credits per second | $0.100 / second | 2,000 seconds, about 33.3 minutes |
wan2.7-spyciylv | 1080p | 30 credits per second | $0.150 / second | 1,333 seconds, about 22.2 minutes |
wan3.0-video | 480p | 10 credits per second | $0.050 / second | 4,000 seconds, about 66.7 minutes |
wan3.0-video | 720p | 20 credits per second | $0.100 / second | 2,000 seconds, about 33.3 minutes |
wan3.0-video | 1080p | 40 credits per second | $0.200 / second | 1,000 seconds, about 16.7 minutes |
z-image-spicy | 256-1536 px | 20 credits per image | $0.100 / image | 2,000 images |
qwen-image-edit-spicy | Follows source image | 8 credits per image | $0.040 / image | 5,000 image edits |
Responses
Create task response
{
"task_id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
"state": "queueing",
"quota": {
"cost": 170,
"base_credits": 170,
"billing_percent": 100,
"discount_percent": 0,
"charged_credits": 170,
"rate_per_second": 34,
"duration": 5,
"resolution": "720p",
"model": "high_quality",
"unit": "second",
"remaining": 830,
"remaining_credits": 830,
"total_credits": 1000,
"used_credits": 170
}
}
Text-to-image create response
{
"task_id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
"state": "queueing",
"status": "pending",
"quota": {
"cost": 20,
"rate_per_second": null,
"duration": null,
"resolution": "1024x1536",
"model": "z-image-spicy",
"unit": "image",
"remaining": 980
}
}
Image edit create response
{
"task_id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
"state": "queueing",
"status": "pending",
"quota": {
"cost": 8,
"rate_per_second": null,
"duration": null,
"resolution": null,
"model": "qwen-image-edit-spicy",
"unit": "image",
"remaining": 992
}
}
Successful task response
{
"id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
"task_id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
"state": "success",
"creations": [
{
"url": "https://media-delivery.example.com/generated-result.mp4"
}
]
}
creations[].url is returned directly for playback or download. Store it only if your product needs a download history.Image result response
{
"task_id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
"state": "success",
"creations": [
{
"url": "https://media-delivery.example.com/generated-image.jpg"
}
]
}
Error handling
| Status | Error | Meaning | Action |
|---|---|---|---|
400 | invalid_json, missing_image, missing_reference_media, missing_headtail_images | The request body is malformed or missing required input. | Validate JSON and required fields before retrying. |
400 | unsupported_billing_unit | The requested model/resolution pair is not configured for credit billing. | Use the model and resolution combinations listed in this document. |
401 | missing_api_key, invalid_api_key | The API key is missing, disabled, expired, or incorrect. | Check the key and contact sales if it should be active. |
402 | quota_exhausted | The customer account has no remaining credits. | Request a quota top-up. |
404 | task_not_found | The task id does not exist or does not belong to this API key. | Use the same customer key that created the task. |
502 | upstream_error | The generation service rejected or failed the task. | Inspect the message, simplify the prompt, or retry later. |
Error response shape
{
"error": "quota_exhausted",
"message": "Quota exhausted"
}
Data handling and privacy
The gateway is designed for quota control, task ownership, and debugging. Customer content is not used for model training or reuse. The system may retain request parameters and prompt text in internal logs for troubleshooting, but it does not store uploaded image/video files or generated media as training data.