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, image-to-video, or reference generation. Each workflow sends a high-quality template value.
Create a taskSend moderation: "disabled" in the JSON body for overseas evaluation traffic.
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",
    "audio": false,
    "moderation": "disabled"
  }'

curl "https://seedance2.lol/ent/v2/tasks/mnt_task_xxxxxxxxx/creations" \
  -H "Authorization: Token mn_live_xxxxxxxxxxxxxxxxx"

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 high-quality 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 one image in images.
wan2.7-i2v-spicy Wan 2.7 image-to-video generation from one first-frame image. /img2video Send this value in the model field. Supports 720p/1080p, 2 to 15 seconds, optional negative_prompt, audio_url, audio, prompt_extend, and seed.
r2v_high_quality Reference-driven video generation from 1 to 9 reference images. /reference2video Use when identity/style consistency matters.
DurationMinimum 4 seconds for high-quality templates; wan2.7-i2v-spicy supports 2 to 15 seconds. Default 5 seconds.
Resolution480p, 720p, and 1080p are available for high-quality template tasks. wan2.7-i2v-spicy supports 720p and 1080p.
AudioOptional. Set audio: true when you want the model to generate native audio.

Text to Video

Create a video directly from a text prompt using the latest high-quality template.

POST/ent/v2/text2video

Request body

FieldTypeRequiredDescription
templatestringYesUse t2v_high_quality.
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 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.
moderationstringYesSend disabled for overseas evaluation calls.
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"
  }'

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 high-quality template path.
modelstringNoUse wan2.7-i2v-spicy to route to the Wan 2.7 image-to-video model.
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.
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 for template tasks. Defaults to false; set true to request generated audio.
negative_promptstringNoOptional for wan2.7-i2v-spicy. Excludes unwanted content.
audio_urlstringNoOptional HTTPS WAV/MP3 URL for wan2.7-i2v-spicy. Duration 2 to 30 seconds, max 15MB.
audiobooleanNoOptional for wan2.7-i2v-spicy. Defaults to true; set false for silent output.
prompt_extendbooleanNoOptional for wan2.7-i2v-spicy. Defaults to true.
seednumberNoOptional random seed for wan2.7-i2v-spicy.
moderationstringYesSend disabled for overseas evaluation calls.
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"
  }'
Wan 2.7 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-spicy",
    "image": "https://example.com/client-owned-first-frame.jpg",
    "prompt": "A premium cinematic shot. Slow push-in, realistic lighting, stable identity.",
    "negative_prompt": "low quality, artifacts",
    "resolution": "1080p",
    "duration": 5,
    "audio": true,
    "prompt_extend": true,
    "moderation": "disabled"
  }'

Reference Generation

Create a video from a prompt plus reference images. 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.
imagesarrayYesOne to nine reference images. Supported formats: png, jpeg, jpg, webp.
promptstringYesPrompt text. Use @1, @2, etc. to refer to image order.
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.
moderationstringYesSend disabled for overseas evaluation calls.
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"
  }'

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 the standard credit reference for high-quality template tasks. Video tasks deduct credits as rate_per_second * duration. Commercial reference pricing uses 1 credit = $0.005; volume top-ups can lower the effective USD rate without changing API credit accounting.

WorkflowResolutionCreditsBase USD reference40,000 credits can generate
High-quality template video480p16 credits per second$0.080 / second2,500 seconds, about 41.7 minutes
High-quality template video720p34 credits per second$0.170 / second1,176 seconds, about 19.6 minutes
High-quality template video1080p85 credits per second$0.425 / second470 seconds, about 7.8 minutes
Example: i2v_high_quality at 720p for 15 seconds costs 34 * 15 = 510 credits, equal to $2.55 at the base reference rate. Customer trial keys are quota-controlled by account.

Responses

Create task response

{
  "task_id": "mnt_task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "state": "queueing",
  "quota": {
    "cost": 170,
    "rate_per_second": 34,
    "duration": 5,
    "resolution": "720p",
    "model": "high_quality",
    "template": "i2v_high_quality",
    "unit": "second",
    "remaining": 900,
    "total_credits": 1000,
    "used_credits": 170
  }
}

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.

Error handling

StatusErrorMeaningAction
400invalid_json, missing_imageThe request body is malformed or missing required input.Validate JSON and required fields before retrying.
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 and task ownership. It does not store customer prompts, uploaded images, or generated media for model training or reuse.

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