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

Models and limits

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

TemplateBest forPublic endpointNotes
t2v_high_quality Text-to-video generation from prompt only. /text2video Send this value in the template field.
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-i2v-spicyh Relay-backed Wan 2.7 spicy image-to-video generation. /img2video Send this value in the model field. Supports image URL or image data URI; the gateway converts image URLs for the relay when needed.
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.
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.
viduq3-ns-flash Fast image-to-video and reference generation with native audio support. /img2video, /reference2video Send this value in the model field. Good for lower-cost testing.
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.
DurationTemplate video routes support up to 15 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 the Q-series NS model routes and supported template 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 the latest high-quality template.

POST/ent/v2/text2video

Request body

FieldTypeRequiredDescription
templatestringNoRecommended: t2v_high_quality. If omitted, the gateway uses this template by default.
modelstringNoUse seedance-2.0-nsfw for the BytePlus Ark NSFW-enabled route. If template is present, template routing takes priority.
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.
durationnumberNo4 to 15 seconds. Send -1 only when automatic duration planning is enabled for your account.
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"
  }'
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 '{
    "template": "t2v_high_quality",
    "prompt": "A premium cinematic 5-second video with realistic motion and soft studio lighting.",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "audio": false,
    "moderation": "disabled"
  }'

Text to Image

Create an image from a text prompt with z-image-spicy. The gateway submits an asynchronous task to MuleRouter and returns a public mnt_task_... id for polling.

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

Request body

FieldTypeRequiredDescription
modelstringNoUse z-image-spicy. It is also the default when omitted.
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.
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
  }'
Asynchronous response: poll the returned public task id through GET /ent/v2/tasks/{task_id}/creations. The completed image URL is returned in creations[0].url.

Image Edit

Edit one source image with qwen-image-edit-spicy. The gateway forwards the image and prompt to MuleRouter as an asynchronous task.

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

Request body

FieldTypeRequiredDescription
modelstringNoUse qwen-image-edit-spicy. It is also the default when omitted.
imagestringYesSource image URL or base64 image data URI to edit.
imagesarrayNoAlternative input. When provided, images[0] is used as the source 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.
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
  }'
Single-image input: this route uses only one source image. Poll the returned public task id through GET /ent/v2/tasks/{task_id}/creations.

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, viduq3-ns-flash, and wan2.7-i2v-spicyh.
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 Relay 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-i2v-spicyh",
    "image": "https://example.com/source.jpg",
    "prompt": "A cinematic 5-second image-to-video shot with smooth realistic motion.",
    "duration": 5,
    "resolution": "720p",
    "prompt_optimization": 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
templatestringYesUse r2v_high_quality.
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.
durationnumberNo4 to 15 seconds. Default is 5.
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"
  }'

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
templatestringYesUse headtail_high_quality.
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.
durationnumberNo4 to 15 seconds. Send -1 when automatic duration planning is enabled by the upstream template.
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"
  }'

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
t2v_high_quality / i2v_high_quality / r2v_high_quality / headtail_high_quality480p16 credits per second$0.080 / second2,500 seconds, about 41.7 minutes
t2v_high_quality / i2v_high_quality / r2v_high_quality / headtail_high_quality720p34 credits per second$0.170 / second1,176 seconds, about 19.6 minutes
t2v_high_quality / 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
viduq3-ns-flash720p10 credits per second$0.050 / second4,000 seconds, about 66.7 minutes
viduq3-ns-flash1080p16 credits per second$0.080 / second2,500 seconds, about 41.7 minutes
wan2.7-i2v-spicyh720p / 1080p34 / 85 credits per secondRelay-backed route reference2-15 seconds, prompt optimization supported
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.