VidMage

VidMage is an AI video and image creation platform for creators. Turn your ideas and images into videos and fresh visuals.

Open the creator tools
Explore APIs
AI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
Build with VidMage
QuickstartAPI keysVidMage MCPError reference
Your account
Developer consoleAbout VidMagePlans and creditsAPI billingContact support
© 2026 VidMage. All rights reserved.
Privacy PolicyTerms of ServiceReport Abuse
Skip to content
VidMage/Developers
Overview
APIs
All APIsAI Video APIsAI Image APIsAI Audio APIsAI 3D APIsAI Face Swap APIsAI Effects APIs
DocumentationVidMage MCPOpen console
Developers/Wan Video API

Wan Video API

Integrate Wan video generation for prompts, starting images, or media references. Use the standard capability for text-only requests, or Wan 3.0 for image and reference workflows with optional audio generation.

Get API keyView API docs
Abstract illustration for Wan Video API
PlaygroundAPIPricingGuideFAQs

Wan Video API Playground

Use your existing API key and subscription. Submitting a generation uses credits; uploading and preparing a request does not start a generation.

API access is available to subscribers only. Your subscription credits are shared across the website and the API.

View plans

Parameter

13 parameters

Text prompt describing the video to generate (max 5000 chars). Optional only in provider modes whose image input fully defines the generation.(Optional)

Optional input image URL. When provided, the task runs in image-to-video mode. In that mode, output ratio is inferred from the input image.(Optional)

Optional multimodal reference images. Public URLs only; images and videos together are limited to 5.(Optional)

maxItems 5

Optional multimodal reference videos. Images and videos together are limited to 5.(Optional)

maxItems 5

Optional multimodal reference audio..(Optional)

maxItems 1

Optional public URL for the final frame in image-to-video mode.(Optional)

Video duration in seconds.(Optional)

Default: 5

Output aspect ratio for modes that expose a ratio parameter. Ignored when imageUrl selects a mode whose ratio is inferred from the input image.(Optional)

Default: 16:9

Output resolution tier.(Optional)

Default: 720p

Optional background music or audio track.(Optional)

Describe unwanted video content or artifacts.(Optional)

Rewrite and enrich the prompt automatically.(Optional)

Default: true

Random seed; leave unset for a random result.(Optional)

min 0max 2147483647

Request code

#!/usr/bin/env bash
set -euo pipefail
# Set this once per intended task; preserve it and the body for transport retries.
: "${VIDMAGE_IDEMPOTENCY_KEY:?Set a unique key for this task}"

SUBMIT_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/wan-ai-video-generator/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "duration": "5",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "promptExtend": true
}')"
TASK_ID="$(printf '%s' "$SUBMIT_RESPONSE" | jq -er '.["taskId"]')"

while true; do
  QUERY_RESPONSE="$(curl --fail-with-body --silent --show-error -X POST "https://vidmage.ai/api/v1/wan-ai-video-generator/query" \
    -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data-raw "{\"taskId\":\"${TASK_ID}\"}")"
  STATUS="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.status // .data.status // "") | ascii_downcase')"
  case "$STATUS" in
    success|succeeded|completed)
      RESULT="$(printf '%s' "$QUERY_RESPONSE" | jq -r '(.result // .["videoUrl"] // .data["videoUrl"] // empty)')"
      if [ -z "$RESULT" ]; then
        printf '%s' "Result missing; preserve task $TASK_ID and query the same task again. Do not resubmit." >&2
        exit 2
      fi
      printf '%s\n' "$RESULT"
      break
      ;;
    needs_input)
      printf '%s' "Face selection required; preserve task $TASK_ID" >&2
      exit 2
      ;;
    failed|error)
      printf '%s' "$QUERY_RESPONSE" | jq -r '(.message // .error // .data.error // "Task failed")' >&2
      exit 1
      ;;
  esac
  sleep 5
done

Response data

Submit the task to see the API response here.
PlaygroundCapabilities

API documentation

Submit a request, track the task, and retrieve your result.

EndpointWan AI Video Generator ↓
Inputs
Varies by mode. See input rules below.
Output
Video·videoUrl
EndpointWan 3.0 AI Video Generator ↓
Inputs
Varies by mode. See input rules below.
Output
Video·videoUrl
Request setup & limitsHeaders, input options and media limits

Request headers

Authorization
Bearer YOUR_API_KEY

Keep your API key on your server.

Content-Type
application/json
Idempotency-Key
YOUR_UNIQUE_KEY

Use a new key per task. Reuse it only when retrying the same submission.

Input options & limits

Request controls follow each task's parameter rules; they do not guarantee output properties.

Wan AI Video Generator

Modes: text-to-video, image-to-video, multimodal-video

Additional inputs; requirements vary by mode

prompt imageUrl imageUrls videoUrls audioUrls lastFrameUrl audioUrl

Media limits by mode
  • Image To VideoImage: jpg, jpeg, png, bmp, webp
  • Multimodal VideoImage: jpg, jpeg, png, bmp, webp; up to 5 filesVideo: mp4, mov; up to 5 filesAudio: mp3, wav; up to 1 file
Request controls
  • duration: 14 accepted values; see parameter rules
  • aspectRatio: "16:9", "9:16", "1:1", "4:3", "3:4"
  • resolution: "720p", "1080p"
  • negativePrompt: see parameter rules
  • promptExtend: default true
  • seed: range 0 to 2147483647

Wan 3.0 AI Video Generator

Modes: image-to-video, multimodal-video

Additional inputs; requirements vary by mode

prompt imageUrl imageUrls videoUrls audioUrls lastFrameUrl

Media limits by mode
  • Image To VideoImage: jpg, jpeg, png, bmp, webp; up to 20 MB per file
  • Multimodal VideoImage: jpg, jpeg, png, bmp, webp; up to 20 MB per file; up to 10 filesVideo: mp4, mov; up to 100 MB per file; up to 5 files; 1 to 15 seconds per file; up to 15 seconds combinedAudio: wav, mp3; up to 15 MB per file; up to 5 files; 1 to 15 seconds per file; up to 15 seconds combined
Request controls
  • duration: 29 accepted values; see parameter rules
  • aspectRatio: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16"
  • resolution: "480p", "720p", "1080p"
  • sound: default true
  • enableThinking: default false
  • seed: range 0 to 2147483647

Input retention and output-link lifetime depend on the API contract. Confirm API-specific retention terms before making promises to your users. Upload guide ↗

Wan AI Video Generator

POST /api/v1/wan-ai-video-generator/submit

Full API documentation ↗

Required inputs

Required inputs depend on the selected mode. Check the mode rules below before submitting.

Edit the sample inputs for your own task before submitting.

Wan AI Video Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/wan-ai-video-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A slow crane shot rises above an ancient riverside town as lanterns illuminate the evening mist","duration":"5","aspectRatio":"16:9","resolution":"720p","promptExtend":true}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules13 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringNoNot specifiedText prompt describing the video to generate (max 5000 chars). Optional only in provider modes whose image input fully defines the generation. Maximum length: 5000
imageUrlstringNoNot specifiedOptional input image URL. When provided, the task runs in image-to-video mode. In that mode, output ratio is inferred from the input image. No additional field constraint listed.
imageUrlsstring[]NoNot specifiedOptional multimodal reference images. Public URLs only; images and videos together are limited to 5. Maximum items: 5
videoUrlsstring[]NoNot specifiedOptional multimodal reference videos. Images and videos together are limited to 5. Maximum items: 5
audioUrlsstring[]NoNot specifiedOptional multimodal reference audio.. Maximum items: 1
lastFrameUrlstringNoNot specifiedOptional public URL for the final frame in image-to-video mode. No additional field constraint listed.
durationstringNo"5"Video duration in seconds. Values: "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" · Default: "5"
aspectRatiostringNo"16:9"Output aspect ratio for modes that expose a ratio parameter. Ignored when imageUrl selects a mode whose ratio is inferred from the input image. Values: "16:9", "9:16", "1:1", "4:3", "3:4" · Default: "16:9"
resolutionstringNo"720p"Output resolution tier. Values: "720p", "1080p" · Default: "720p"
audioUrlstringNoNot specifiedOptional background music or audio track. No additional field constraint listed.
negativePromptstringNoNot specifiedDescribe unwanted video content or artifacts. Minimum length: 0 · Maximum length: 500
promptExtendbooleanNotrueRewrite and enrich the prompt automatically. Default: true
seednumberNoNot specifiedRandom seed; leave unset for a random result. Minimum: 0 · Maximum: 2147483647 · Multiple of: 1 · Whole numbers only
Mode-specific fields & media limits
Text To Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 5000 characters
durationValues: "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"; mode default: "5"
aspectRatioValues: "16:9", "9:16", "1:1", "4:3", "3:4"; mode default: "16:9"
resolutionValues: "720p", "1080p"; mode default: "720p"
audioUrlNo additional field constraint listed.
negativePromptMaximum characters: 500
promptExtendDefault: true
seedRange: 0 to 2147483647
Image To Video rules
ControlMode-specific rule
promptOptional; minimum 0 characters; maximum 5000 characters
durationValues: "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"; mode default: "5"
resolutionValues: "720p", "1080p"; mode default: "720p"
imageUrlImage input
lastFrameUrlOptional final-frame image input
audioUrlNo additional field constraint listed.
negativePromptMaximum characters: 500
promptExtendDefault: true
seedRange: 0 to 2147483647
Multimodal Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 5000 characters
durationValues: "2", "3", "4", "5", "6", "7", "8", "9", "10"; mode default: "5"
aspectRatioValues: "16:9", "9:16", "1:1", "4:3", "3:4"; mode default: "16:9"
resolutionValues: "720p", "1080p"; mode default: "1080p"
imageUrlsImage input; up to 5 items
videoUrlsVideo references; up to 5 items
audioUrlsAudio references; up to 1 items
negativePromptMaximum characters: 500
promptExtendDefault: true
seedRange: 0 to 2147483647

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/wan-ai-video-generator/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Wan AI Video Generator query
curl -X POST "https://vidmage.ai/api/v1/wan-ai-video-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Wan 3.0 AI Video Generator

POST /api/v1/wan-3-0-ai-video-generator/submit

Full API documentation ↗

Required inputs

Required inputs depend on the selected mode. Check the mode rules below before submitting.

Edit the sample inputs for your own task before submitting.

Wan 3.0 AI Video Generator request
# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/wan-3-0-ai-video-generator/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp","prompt":"Use Image 1 for the character, Video 1 for the camera rhythm, and Audio 1 for the timing of a cinematic city walk","duration":"5","aspectRatio":"adaptive","resolution":"720p","sound":true,"enableThinking":false}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules12 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringNoNot specifiedText prompt describing the video to generate (max 20000 chars). Optional only in provider modes whose image input fully defines the generation. Maximum length: 20000
imageUrlstringNoNot specifiedInput image URL for image-to-video mode. Omit it only when supplying multimodal reference arrays instead. No additional field constraint listed.
imageUrlsstring[]NoNot specifiedOptional multimodal reference images. Public URLs only; 20 MB per file. Maximum items: 10
videoUrlsstring[]NoNot specifiedOptional multimodal reference videos. Each video is 1–15 seconds and 100 MB max. Maximum items: 5
audioUrlsstring[]NoNot specifiedOptional multimodal reference audio. Each audio is 1–15 seconds and 15 MB max. Maximum items: 5
lastFrameUrlstringNoNot specifiedOptional public URL for the final frame in image-to-video mode. No additional field constraint listed.
durationstringNo"5"Video duration in seconds. Values: "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30" · Default: "5"
aspectRatiostringNo"adaptive"Output aspect ratio. Values: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16" · Default: "adaptive"
resolutionstringNo"720p"Output resolution tier. Values: "480p", "720p", "1080p" · Default: "720p"
soundbooleanNotrueGenerate synchronized audio along with the video. No separate sound surcharge is configured. Default: true
enableThinkingbooleanNofalseEnable deeper reasoning before generating the video. Default: false
seednumberNoNot specifiedRandom seed; leave unset for a random result. Minimum: 0 · Maximum: 2147483647 · Multiple of: 1 · Whole numbers only
Mode-specific fields & media limits
Image To Video rules
ControlMode-specific rule
promptOptional; minimum 0 characters; maximum 20000 characters
durationValues: "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30"; mode default: "5"
aspectRatioValues: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16"; mode default: "adaptive"
resolutionValues: "480p", "720p", "1080p"; mode default: "720p"
soundBoolean control; default true
imageUrlImage input
lastFrameUrlOptional final-frame image input
enableThinkingDefault: false
seedRange: 0 to 2147483647
Multimodal Video rules
ControlMode-specific rule
promptRequired; minimum 1 characters; maximum 20000 characters
durationValues: "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30"; mode default: "5"
aspectRatioValues: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16"; mode default: "adaptive"
resolutionValues: "480p", "720p", "1080p"; mode default: "1080p"
soundBoolean control; default true
imageUrlsImage input; up to 10 items
videoUrlsVideo references; up to 5 items
audioUrlsAudio references; up to 5 items
enableThinkingDefault: false
seedRange: 0 to 2147483647

Retrieve the result

Save taskId from the accepted submission and send it to this endpoint:

POST /api/v1/wan-3-0-ai-video-generator/query

Use the same Bearer API key. On completion, read the videoUrl result field.

Task states and recovery ↗
Wan 3.0 AI Video Generator query
curl -X POST "https://vidmage.ai/api/v1/wan-3-0-ai-video-generator/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }

Pricing

See what one image, video, or generation costs in credits. Your API and website activity share the same credit balance.

API credit rates and calculated example request costs
API / workflowExample requestPrice (credits)
Wan AI Video Generatorvideo API5-second video: 75 creditsresolution: 720p
How this is calculated
  • 720p: 15 credits / second
  • 1080p: 30 credits / second

Base charge = duration × the selected resolution rate.

Estimate your own request ↗
15–30 credits / secondBase rate varies by settings or workflow
Wan 3.0 AI Video Generatorvideo API5-second video: 75 creditsresolution: 720p · sound: true
How this is calculated
  • 480p: 10 credits / second
  • 720p: 15 credits / second
  • 1080p: 30 credits / second

Base charge = duration × the selected resolution rate.

Including reference video adds a flat charge: 480p: 50 credits; 720p: 75 credits; 1080p: 150 credits.

Estimate your own request ↗
10–30 credits / secondBase rate varies by settings or workflow
Billed in credits. Shared with the website.Active subscription required. Unit rates and examples follow current API credit rules.Billing details⌄

Examples show the charge for the inputs listed above. Resolution, duration, audio, output count and reference media can change the total. Minimum charges and rounding follow the selected API.

Use the Playground to estimate your request before submitting it. Estimates do not start a generation. Subscription and credit-pack prices are listed on the plans page.

Your task’s recorded usage is the source of truth for the final charge.

View plans ↗Billing guide ↗

About Wan Video API

VidMage's Wan Video API separates standard Wan from Wan 3.0. Standard Wan supports text-only generation; Wan 3.0 uses starting images or reference media. Image, video, and audio inputs follow each capability's own limits and controls. A short drama workspace can combine text-led establishing shots with reference-guided character scenes, bringing the selected clips together on an episode timeline. To explore this model's browser workflow, open VidMage's Wan AI Video Generator.

Wan Video API capabilities

Generate a scene from text
Use the standard Wan capability for prompt-only video generation, with its own negative-prompt and prompt-expansion controls.
Animate an existing image
Provide a starting image and describe the motion you want through a capability that accepts that input.
Combine media guidance
Build reference-based requests with image, video, and audio inputs, following the selected capability's limits and field names.

What you can build

Short drama scene workspaces

Use standard Wan to establish a location from text, and Wan 3.0 to develop a character scene from references. Keeping both kinds of footage under the same episode brief helps your editing workspace connect setting shots with story action.

Product demonstration concepts

Show a seller what a proposed product shot could look like. A product photo establishes the item, while a motion reference suggests a turn or reveal through a compatible mode. Product details remain part of the selection review.

Animated book teasers

Curtains part around a figure from the cover. A landscape from an illustrated chapter comes into motion. Starting with existing book artwork gives publishers a visual basis for a teaser, with titles and release details added in their editor.

How to use Wan Video API

  1. Get an API key

    Create a key in the Developer Console and store it on your server. Use it in the Authorization: Bearer header.

  2. Prepare and submit your inputs

    Set up your inputs in the Playground, then copy the matching API request. Send it from your server with a unique Idempotency-Key.

  3. Track the task

    Save the returned taskId and query the same operation until it completes. Keep that identifier if your app stops waiting.

  4. Retrieve the result

    Read videoUrl from the completed task. Preview the result in your app and save a copy to your own storage for later use.

Input tips
Choose the capability by input
The reviewed Wan 3.0 modes require a starting image or reference media. Choose the standard Wan capability when your request begins only with a written scene.
Respect separate reference budgets
Standard Wan permits five combined references and names audioUrl. Wan 3.0 uses audioUrls and separate capacities, with video and audio references each limited to fifteen seconds total.

Input requirementsUpload local files

Task fields and results

Keep the task identifier with its original request and Idempotency-Key. Query the same capability until it completes, then read the documented result field.

Task identifier
taskId
Query route
POST /api/v1/wan-ai-video-generator/query
Completed result
videoUrl
Task states and response structure ↗
Errors, retries and limits

Retry transport failures with the same idempotency key only when the original submission may not have reached the server. For a confirmed task, keep querying the original task instead of submitting a duplicate.

Read error recovery guidance ↗

FAQs

Are failed or timed-out requests charged?

A client timeout is not a confirmed task failure. Confirmed failures are automatically refunded only when the refund outcome is certain. Unknown charges or refunds remain pending reconciliation.

Failure and refund handling ↗
How long should my app wait for a result?

The checked contract does not establish a fixed completion time. Choose a local wait budget for your app; it is not an API completion deadline.

Polling and wait budgets ↗
What are the rate and concurrency limits?

Request-rate limits control how often you can call the API; concurrency limits control simultaneous work. The documentation ties both to the stable API key but does not publish numeric limits for this operation. Confirm account limits before planning parallel jobs.

Rate-limit recovery ↗
Can I receive results through a webhook?

The checked request contract documents status queries and does not list a webhook or callback field for these routes. Check the current authenticated OpenAPI contract before making a callback part of your integration.

Query task results ↗Check the current contract ↗

Explore more APIs on VidMage

  • Wan Image API↗
  • HappyHorse API↗
  • Hailuo API↗
  • Veo 3.1 API↗
  • Kling API↗
  • Grok Video API↗
  • SkyReels API↗
  • Sora 2 API↗