API integration guide

Connect to private video generation with one API key.

This document explains how business clients authenticate, create video generation tasks, poll task status, receive media URLs, and manage quota usage through the Minuit API.

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.

Choose one workflowUse text-to-video, text-to-image, image-edit, image-to-video, reference generation, or head-tail frame generation. Image generation uses z-image-spicy; single-image editing uses qwen-image-edit-spicy. Both image routes are processed asynchronously through MuleRouter.
Create a taskSend moderation: "disabled" for regular overseas routes. For seedance-2.0-nsfw, the Ark route is forwarded with moderation: "skip" according to the provider document.
Store the returned task idThe public task id starts with mnt_task_. Use it for polling.
Download or display the media URLWhen the task succeeds, use creations[0].url as the generated asset URL.
Minimal cURL flow
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"
Asset inputs: for production integrations, prefer HTTPS URLs in 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.

Recommended headerAuthorization: Token mn_live_xxxxx
Alternative headersAuthorization: Bearer mn_live_xxxxx or x-api-key: mn_live_xxxxx
Security note: customer keys are quota-limited and can be disabled. If a key is leaked, contact sales immediately so it can be rotated.

Unified 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.

Create videoPOST /v1/videos
Retrieve videoGET /v1/videos/{video_id}
Download contentGET /v1/videos/{video_id}/content
Automatic routing: omit reference assets for text-to-video, or send one input_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.
Authentication: send 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.
Native audio extension: 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.
Text to Video
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"
Image to Video
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"
Head-tail Frame Video
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"
Multimodal Reference Video
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"
Retrieve and download
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
FieldTypeRequiredDescription
modelstringNoPublic model name. Defaults to the gateway's current video model.
promptstringYesOne complete prompt. Line breaks do not create multiple tasks.
input_referencefile or stringNoOne uploaded image, data URI, or HTTPS image URL. If supplied without a mode, the request is routed to image-to-video.
secondsnumberNoRequested output duration. Defaults to 5 seconds; model-specific limits still apply.
sizestringNoOpenAI-style dimensions such as 1280x720 or 720x1280. The gateway derives resolution and aspect ratio from this value.
audiobooleanNoMinuit extension for seedance-2.0-nsfw. Send true for synchronized native audio or false for silent output. Defaults to false.
metadataJSON object or JSON stringNoAdvanced routing and reference assets. In multipart requests, send it as a JSON string.
metadata.modestringFor advanced modesheadtail2video for exactly two ordered images, or reference2video for multimodal references.
metadata.imagesstring[]Mode-specificOrdered HTTPS image URLs. Head-tail mode requires exactly two. Reference mode accepts one or more.
metadata.video_urlsstring[]NoOptional reference videos for reference2video.
metadata.audio_urlsstring[]NoOptional reference audio for reference2video. Reference mode still requires at least one image or video.
Upstream mapping: Minuit converts these simplified fields into the official upstream content roles, including 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.
Moderation: customers do not need to send a moderation field for seedance-2.0-nsfw. The gateway applies the configured upstream moderation strategy server-side.
Backward compatibility: the native /ent/v2/text2video, /ent/v2/img2video, /ent/v2/reference2video, and /ent/v2/headtail2video endpoints remain available for existing integrations.
Content response: after checking the key and task ownership, the content endpoint redirects to the completed upstream media URL. Clients should follow HTTP redirects.

Models and limits

Use the model and template names below. Internal routing, overseas upstream calls, and credentials are handled by the Minuit API gateway.

Prompt length: 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.
TemplateBest forPublic endpointNotes
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.
Model Studio upstream inspection header: for 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.
DurationTemplate video routes support up to 15 seconds. wan3.0-video supports 2-30 seconds. Default duration is 5 seconds.
ResolutionTemplate routes support 480p, 720p, and 1080p where available. Q-series NS routes support 720p and 1080p.
AudioNative audio is available on supported Seedance and Wan routes when enabled.
Task ids: Vidu template and async image tasks return 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.

POST/ent/v2/text2video

Request body

FieldTypeRequiredDescription
modelstringNoUse seedance-2.0-nsfw, wan3.0-video, or wan2.7-spyciylv. If omitted, the gateway defaults to wan3.0-video.
promptstringYesVideo prompt with subject, action, camera, style, lighting, and timing.
resolutionstringNo480p, 720p, or 1080p. Defaults to 720p.
aspect_ratiostringNo16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive.
durationnumberNoRegular routes support up to 15 seconds. wan3.0-video supports 2-30 seconds and also accepts -1 for smart duration.
audiobooleanNoOptional native audio switch. Defaults to false; send true only when audio is needed.
callback_urlstringNoOptional webhook URL for task state updates.
moderationstringYesRegular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream.
Seedance 2.0 NSFW Ark Text to Video example
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"
  }'
Wan 2.7 Model Studio Text to Video example
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
  }'
Wan 3.0 Text to Video example
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
  }'
No additional client header required: the gateway adds 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.

POST/ent/v2/text2image
POST/ent/v2/text2img

Request body

FieldTypeRequiredDescription
modelstringNoUse z-image-spicy or qwen-image-3.0-pro. The default is z-image-spicy.
promptstringYesImage prompt with subject, style, composition, lighting, and detail requirements.
widthintegerNoOutput width from 256 to 1536 pixels. Defaults to 1024.
heightintegerNoOutput height from 256 to 1536 pixels. Defaults to 1536.
aspect_ratiostringNoConvenience 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.
seednumber/nullNoOptional random seed. Omit it for automatic seed selection.
prompt_extendbooleanNoEnable prompt expansion. Defaults to true.
nintegerNoImage 3 only: number of images, 1-6. Each output is billed separately.
negative_promptstringNoImage 3 only: describe content to avoid.
Qwen Image 3 Text to Image example
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
  }'
Text to Image example
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
  }'
Image 3 response: HTTP 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.
Safe retries and recovery (Image 3): send a unique 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.
Recover a task after a disconnected creation request
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"
Unconfirmed results: HTTP/network errors while polling do not mean generation failed. Retry the query, not a new generation. 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.

POST/ent/v2/image2image
POST/ent/v2/reference2image

Request body

FieldTypeRequiredDescription
modelstringNoUse qwen-image-edit-spicy or qwen-image-3.0-pro.
imagestringYesSource image URL or base64 image data URI to edit.
imagesarrayNoAlternative input. Image 3 accepts 1-3 image URLs or Base64 data URIs; qwen-image-edit-spicy uses the first image.
promptstringYesText instruction describing the edit, such as changing background, adding/removing elements, or applying a style.
seednumber/nullNoOptional random seed. Omit it for random generation.
Qwen Image 3 multi-reference edit example
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
  }'
Image 3 response and retention: HTTP 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.
Long-running image edits: the browser/client no longer waits on upstream generation. Image 3 editing uses the same idempotency and request-recovery flow as text-to-image above. Raw input parameters (including any Base64 references) are held temporarily in a service-only queue and cleared when processing ends; the existing sanitized request log is retained.
Image Edit example
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
  }'
Input behavior: 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.

POST/ent/v2/img2video

Request body

FieldTypeRequiredDescription
templatestringNoUse i2v_high_quality for the first-frame template path. If template is present, it takes priority over regular model routing.
modelstringNoOptional model selector. Supported regular routes include seedance-2.0-nsfw, wan3.0-video, and wan2.7-spyciylv.
imagesarrayYesOne image URL or image data URI. The image is used as the first frame.
imagestringNoAlternative single-image field. Use either images or image.
promptstringYesVideo direction, camera movement, style, timing, and scene details.
resolutionstringNo480p, 720p, or 1080p. Defaults to 720p.
durationnumberNo4 to 15 seconds for template routing. Default is 5.
aspect_ratiostringNo16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive.
audiobooleanNoOptional native audio switch. Defaults to false.
moderationstringYesRegular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream.
callback_urlstringNoOptional webhook URL for task state updates.
Image to Video example
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"
  }'
Seedance 2.0 NSFW Ark Image to Video example
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"
  }'
Wan 2.7 Model Studio Image to Video example
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
  }'
Wan 2.7 aspect ratio: image-to-video follows the uploaded first frame. The 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.
Wan 3.0 Image to Video example
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.

POST/ent/v2/reference2video

Request body

FieldTypeRequiredDescription
templatestringNoUse r2v_high_quality for template routing, or omit it and set model to wan3.0-video or wan2.7-spyciylv.
imagesarrayYesReference images. Supported formats: png, jpeg, jpg, webp.
promptstringYesPrompt text. Use @1, @2, etc. to refer to image order.
video_urlsarrayNoOptional video references. Supports up to 3 MP4 or MOV URLs.
resolutionstringNo480p, 720p, or 1080p. Defaults to 720p.
aspect_ratiostringNo16:9, 9:16, 1:1, 4:3, or 3:4. Defaults to 16:9.
durationnumberNoRegular routes support up to 15 seconds. wan3.0-video supports up to 30 seconds, subject to the 30-second combined input/output video limit.
audiobooleanNoOptional native audio switch. Defaults to false.
callback_urlstringNoOptional webhook URL for task state updates.
moderationstringYesRegular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream.
Seedance 2.0 NSFW Ark Reference Generation example
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"
  }'
Reference Generation example
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"
  }'
Reference Generation with video reference
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"
  }'
Wan 2.7 Model Studio Multi-reference example
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
  }'
Wan 3.0 Multi-reference example
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.

POST/ent/v2/headtail2video

Request body

FieldTypeRequiredDescription
templatestringNoUse headtail_high_quality for template routing, or omit it and set model to wan3.0-video or wan2.7-spyciylv.
imagesarrayYesExactly two images. images[0] is the first frame; images[1] is the last frame.
promptstringYesPrompt describing the motion, transition, camera, and visual style between the two frames.
video_urlsarrayNoOptional reference videos. 0 to 3 items.
audio_urlsarrayNoOptional reference audio files. 0 to 3 items.
resolutionstringNo480p, 720p, or 1080p. Defaults to 720p.
aspect_ratiostringNo16:9, 9:16, 1:1, 4:3, 3:4, 21:9, or adaptive.
durationnumberNoRegular routes support up to 15 seconds. wan3.0-video supports 2-30 seconds and smart duration with -1.
audiobooleanNoOptional native audio switch. Defaults to false; send true only when audio is needed.
callback_urlstringNoOptional webhook URL for task state updates.
moderationstringYesRegular routes accept disabled. For seedance-2.0-nsfw, the server forwards skip to the Ark upstream.
Head-tail Frame Video example
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"
  }'
Wan 2.7 Model Studio Head-tail Frame example
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
  }'
Wan 2.7 routing: the gateway maps this request to 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.

GET/ent/v2/tasks/{task_id}/creations
JavaScript polling example
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.

WorkflowResolutionCreditsBase USD reference40,000 credits can generate
i2v_high_quality / r2v_high_quality / headtail_high_quality480p16 credits per second$0.080 / second2,500 seconds, about 41.7 minutes
i2v_high_quality / r2v_high_quality / headtail_high_quality720p34 credits per second$0.170 / second1,176 seconds, about 19.6 minutes
i2v_high_quality / r2v_high_quality / headtail_high_quality1080p85 credits per second$0.425 / second470 seconds, about 7.8 minutes
seedance-2.0-nsfw480p28 credits per second$0.140 / second1,428 seconds, about 23.8 minutes
seedance-2.0-nsfw720p60 credits per second$0.300 / second666 seconds, about 11.1 minutes
seedance-2.0-nsfw1080p150 credits per second$0.750 / second266 seconds, about 4.4 minutes
wan2.7-spyciylv720p20 credits per second$0.100 / second2,000 seconds, about 33.3 minutes
wan2.7-spyciylv1080p30 credits per second$0.150 / second1,333 seconds, about 22.2 minutes
wan3.0-video480p10 credits per second$0.050 / second4,000 seconds, about 66.7 minutes
wan3.0-video720p20 credits per second$0.100 / second2,000 seconds, about 33.3 minutes
wan3.0-video1080p40 credits per second$0.200 / second1,000 seconds, about 16.7 minutes
z-image-spicy256-1536 px20 credits per image$0.100 / image2,000 images
qwen-image-edit-spicyFollows source image8 credits per image$0.040 / image5,000 image edits
Seedance 2.0 NSFW examples: 480p costs 140 credits for 5 seconds and 280 for 10 seconds; 720p costs 300 and 600 credits; 1080p costs 750 and 1,500 credits. Web evaluation codes use a simplified quota rule: each Seedance 2.0 NSFW test consumes 5 trial credits, regardless of duration or resolution, and failed tasks are refunded.

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"
    }
  ]
}
Media URL behavior: the generated 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

StatusErrorMeaningAction
400invalid_json, missing_image, missing_reference_media, missing_headtail_imagesThe request body is malformed or missing required input.Validate JSON and required fields before retrying.
400unsupported_billing_unitThe requested model/resolution pair is not configured for credit billing.Use the model and resolution combinations listed in this document.
401missing_api_key, invalid_api_keyThe API key is missing, disabled, expired, or incorrect.Check the key and contact sales if it should be active.
402quota_exhaustedThe customer account has no remaining credits.Request a quota top-up.
404task_not_foundThe task id does not exist or does not belong to this API key.Use the same customer key that created the task.
502upstream_errorThe 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.

No trainingCustomer inputs and outputs are not used to train models.
No reuseGenerated output is not reused for other customers or public case libraries.
Operational recordsThe system stores customer key hash, quota ledger, task ownership, and request logs needed for support.
Implementation note: task ownership is checked on every polling request, so one customer cannot query another customer's task id.