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_xxxxxx-api-key: mn_live_xxxxxModels and limits
Use the model and template names below. Internal routing, overseas upstream calls, and credentials are handled by the Minuit API gateway.
| Template | Best for | Public endpoint | Notes |
|---|---|---|---|
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. |
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 the latest high-quality template.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
template | string | No | Recommended: t2v_high_quality. If omitted, the gateway uses this template by default. |
model | string | No | Use seedance-2.0-nsfw for the BytePlus Ark NSFW-enabled route. If template is present, template routing takes priority. |
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 | 4 to 15 seconds. Send -1 only when automatic duration planning is enabled for your account. |
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 '{
"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.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | No | Use z-image-spicy. It is also the default when omitted. |
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. |
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
}'
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.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | No | Use qwen-image-edit-spicy. It is also the default when omitted. |
image | string | Yes | Source image URL or base64 image data URI to edit. |
images | array | No | Alternative input. When provided, images[0] is used as the source 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 "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
}'
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.
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, viduq3-ns-flash, and wan2.7-i2v-spicyh. |
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-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.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
template | string | Yes | Use r2v_high_quality. |
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 | 4 to 15 seconds. Default is 5. |
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"
}'
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 | Yes | Use headtail_high_quality. |
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 | 4 to 15 seconds. Send -1 when automatic duration planning is enabled by the upstream template. |
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"
}'
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 |
|---|---|---|---|---|
t2v_high_quality / i2v_high_quality / r2v_high_quality / headtail_high_quality | 480p | 16 credits per second | $0.080 / second | 2,500 seconds, about 41.7 minutes |
t2v_high_quality / i2v_high_quality / r2v_high_quality / headtail_high_quality | 720p | 34 credits per second | $0.170 / second | 1,176 seconds, about 19.6 minutes |
t2v_high_quality / 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 |
viduq3-ns-flash | 720p | 10 credits per second | $0.050 / second | 4,000 seconds, about 66.7 minutes |
viduq3-ns-flash | 1080p | 16 credits per second | $0.080 / second | 2,500 seconds, about 41.7 minutes |
wan2.7-i2v-spicyh | 720p / 1080p | 34 / 85 credits per second | Relay-backed route reference | 2-15 seconds, prompt optimization supported |
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.