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/AI Video Generation API for Text and Images

AI Video Generation API for Text and Images

Build video generation into your app from text prompts or a starting image. Set duration, aspect ratio, and resolution, with an optional ending image for image-to-video requests.

Get API keyView API docs
Abstract illustration for AI Video Generation API for Text and Images
PlaygroundAPIPricingGuideFAQs

AI Video Generation 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

4 parameters

Text description of the video to generate.

Video duration in seconds.(Optional)

Default: 5

Aspect ratio.(Optional)

Default: adaptive

Output resolution.(Optional)

Default: 720p

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/text-to-video/submit" \
  -H "Authorization: Bearer ${VIDMAGE_API_KEY}" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "prompt": "A vintage red convertible drives along a coastal road at golden hour, smooth cinematic tracking shot",
  "duration": "5",
  "ratio": "adaptive",
  "resolution": "720p"
}')"
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/text-to-video/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.

EndpointText to Video ↓
Required inputs
prompt
Output
Video·videoUrl
EndpointImage to Video ↓
Required inputs
firstFrameImageUrl prompt
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.

Text to Video

Requiredprompt
Request controls
  • duration: 12 accepted values; see parameter rules
  • ratio: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9"
  • resolution: "480p", "720p", "1080p", "2k", "4k"

Image to Video

RequiredfirstFrameImageUrl prompt
Optional inputslastFrameImageUrl
Request controls
  • duration: 12 accepted values; see parameter rules
  • ratio: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9"
  • resolution: "480p", "720p", "1080p", "2k", "4k"

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

Text to Video

POST /api/v1/text-to-video/submit

Full API documentation ↗

prompt is required.

Required inputs

promptstring
Text description of the video to generate.

Edit the sample inputs for your own task before submitting.

Text to Video 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/text-to-video/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A vintage red convertible drives along a coastal road at golden hour, smooth cinematic tracking shot","duration":"5","ratio":"adaptive","resolution":"720p"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules4 fields
FieldTypeRequiredDefaultMeaning and limits
promptstringYesNot specifiedText description of the video to generate. No additional field constraint listed.
durationstringNo"5"Video duration in seconds. Values: "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" · Default: "5"
ratiostringNo"adaptive"Aspect ratio. Values: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" · Default: "adaptive"
resolutionstringNo"720p"Output resolution. Values: "480p", "720p", "1080p", "2k", "4k" · Default: "720p"

Retrieve the result

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

POST /api/v1/text-to-video/query

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

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

Image to Video

POST /api/v1/image-to-video/submit

Full API documentation ↗

firstFrameImageUrl is required and prompt is required.

Required inputs

firstFrameImageUrlstring
URL of the first frame image.
promptstring
Text description of the motion / scene.

Edit the sample inputs for your own task before submitting.

Image to Video 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/image-to-video/submit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"firstFrameImageUrl":"https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp","prompt":"The subject gently turns toward the camera as a light breeze moves the hair and background leaves","duration":"5","ratio":"adaptive","resolution":"720p"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }
Parameters and input rules6 fields
FieldTypeRequiredDefaultMeaning and limits
firstFrameImageUrlstringYesNot specifiedURL of the first frame image. No additional field constraint listed.
lastFrameImageUrlstringNoNot specifiedURL of the last frame image (optional). No additional field constraint listed.
promptstringYesNot specifiedText description of the motion / scene. No additional field constraint listed.
durationstringNo"5"Video duration in seconds. Values: "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15" · Default: "5"
ratiostringNo"adaptive"Aspect ratio. Values: "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" · Default: "adaptive"
resolutionstringNo"720p"Output resolution. Values: "480p", "720p", "1080p", "2k", "4k" · Default: "720p"

Retrieve the result

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

POST /api/v1/image-to-video/query

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

Task states and recovery ↗
Image to Video query
curl -X POST "https://vidmage.ai/api/v1/image-to-video/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)
Text to Videovideo API5-second video: 100 creditsresolution: 720p
How this is calculated
  • 480p: 10 credits / second
  • 720p: 20 credits / second
  • 1080p: 25 credits / second
  • 2k: 30 credits / second
  • 4k: 35 credits / second

Charge = duration × the selected resolution rate.

Estimate your own request ↗
10–35 credits / secondBase rate varies by settings or workflow
Image to Videovideo API5-second video: 100 creditsresolution: 720p
How this is calculated
  • 480p: 10 credits / second
  • 720p: 20 credits / second
  • 1080p: 25 credits / second
  • 2k: 30 credits / second
  • 4k: 35 credits / second

Charge = duration × the selected resolution rate.

Estimate your own request ↗
10–35 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 AI Video Generation API

Build video scenes from a written description or a starting image with VidMage's AI Video Generation API. Duration, framing, and resolution controls shape the request, and image-guided generation can use an optional ending frame. For a short drama app, each script beat or storyboard frame can lead to a scene clip that your editor assembles into an episode. To explore video creation before integrating the API, open VidMage's AI Video Generator.

AI Video Generation API capabilities

Text-to-video generation
Start a new clip with a prompt describing the subject, scene, action, and intended camera behavior.
Image-guided generation
Supply a starting image and prompt, with an optional ending image to guide the requested video.
Video output settings
Configure the documented duration, aspect ratio, and resolution options for either text-based or image-guided video generation.

What you can build

Short drama generation

Break an episode into scene briefs or begin each shot with a storyboard image. The API generates the individual clips; your editing workspace brings the chosen takes, dialogue, and captions onto an episode timeline.

Product launch videos

A camera orbit or a lid opening can give an existing product image a role in a launch video. Describe that action and choose the supported output settings, leaving pricing and the call to action to your ad layout.

Scenes for video explainers

Some lessons benefit from a visual example, such as a recycling line sorting different materials. Generate an illustrative scene from the teaching brief and pair it with checked narration and labels in the course editor.

How to use AI Video Generation 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
Match the inputs to the mode
Text-to-video requires a prompt. Image-to-video also requires firstFrameImageUrl and accepts lastFrameImageUrl, so update the form when users change how the clip begins.
Keep the request types intact
Duration, ratio, and resolution use string values in this contract. The generic endpoints have no model selector; use a named model API for model-specific settings.

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/text-to-video/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

Should I generate a new clip or edit an existing one?

Use video-to-video to transform existing footage, or AI Video Extender to generate a continuation. These are separate workflows from creating a new clip from text or a still frame.

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

  • AI Video to Video API for Style Transformations↗
  • AI Video Extender API for Clip Continuations↗
  • Sora 2 API↗
  • AI Video Background Remover API for Clips↗
  • Grok Video API↗
  • AI Multi Face Swap API for Photos and Videos↗
  • AI Subtitle Generator API for Video Captions↗
  • PixVerse API↗