REST API · V3

Developer docs

V3 uses base, cinematic, and origin with discovery, quotes, and standalone upscales. V1/V2 retain their original minimax/h3 model names in requests and responses. V3 defaults to prompt enhancement.

Manage API Keys
01

Quickstart

Create an asynchronous video generation, then poll the same Video resource to a terminal state.

1. Create and save the ID

POST returns HTTP 202. Save the top-level id from its JSON response.

2. Retrieve by ID

Append that ID to /v3/videos/ and send a GET request.

3. Download on success

When status is succeeded, download the video from output.url.

Create a project key in API Keys and fund the project, then choose your language below.

Choose a language in any code block header; all steps below stay in sync. Requires Bash, curl, and jq. Run the three steps in the same terminal, or save them as video.sh.

Before you start: set your project API key

Terminal · macOS / Linux
Bash
export VGENV_API_KEY='YOUR_API_KEY'

Replace YOUR_API_KEY. Creation reserves the quoted amount; successful generation settles the charge.

1Initialize the client

video.sh
# 在同一个 Bash 终端中依次执行;需要 curl 和 jq
# 每个新任务用一个新值;请求超时重试时保留原值
IDEMPOTENCY_KEY="video-$(date +%s)-$RANDOM"

2Create a task and save its id

POST /v3/videos returns HTTP 202 on acceptance. Save the top-level id to retrieve the task later.

POST /v3/videos
# 此请求会创建付费任务;先保存响应,再提取任务 ID
CREATE_RESPONSE=$(curl --fail-with-body --silent --show-error \
  https://api.vgenv.com/v3/videos \
  -H "Authorization: Bearer $VGENV_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"base","tier":"fast","prompt":"A boat sails across a quiet lake","duration":5,"resolution":"480p"}') &&
VIDEO_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -er '.id | strings | select(length > 0)') &&
printf 'VIDEO_ID=%s\n' "$VIDEO_ID"
Show creation response
HTTP 202 · JSON
JSON
{
  "id": "job_example123",
  "status": "queued",
  "progress": 0,
  "output": null,
  "error": null
}

The response field is id. Variables named jobId, job_id, or VIDEO_ID hold that same value. Replace job_example123 with the actual returned ID.

3Poll status and download on success

Poll every 5 seconds. Download output.url on succeeded; stop on failure or cancellation.

GET /v3/videos/:videoId → video.mp4
# 延续创建步骤中的 VIDEO_ID;每 5 秒查询一次
while true; do
  VIDEO=$(curl --fail-with-body --silent --show-error \
    "https://api.vgenv.com/v3/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $VGENV_API_KEY") || break
  STATUS=$(printf '%s' "$VIDEO" | jq -er '.status') || break
  printf 'status=%s\n' "$STATUS"
  case "$STATUS" in
    preparing|queued|running) sleep 5 ;;
    succeeded)
      OUTPUT_URL=$(printf '%s' "$VIDEO" | jq -er '.output.url | strings | select(length > 0)') || break
      curl --fail --location --output video.mp4 "$OUTPUT_URL"
      break ;;
    failed|cancelled)
      printf '%s' "$VIDEO" | jq '{id,status,error}'
      break ;;
    *) printf 'Unexpected status: %s\n' "$STATUS" >&2; break ;;
  esac
done
Copy the complete script and run command
video.sh
# 在同一个 Bash 终端中依次执行;需要 curl 和 jq
# 每个新任务用一个新值;请求超时重试时保留原值
IDEMPOTENCY_KEY="video-$(date +%s)-$RANDOM"

# 此请求会创建付费任务;先保存响应,再提取任务 ID
CREATE_RESPONSE=$(curl --fail-with-body --silent --show-error \
  https://api.vgenv.com/v3/videos \
  -H "Authorization: Bearer $VGENV_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"base","tier":"fast","prompt":"A boat sails across a quiet lake","duration":5,"resolution":"480p"}') &&
VIDEO_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -er '.id | strings | select(length > 0)') &&
printf 'VIDEO_ID=%s\n' "$VIDEO_ID"

# 延续创建步骤中的 VIDEO_ID;每 5 秒查询一次
while true; do
  VIDEO=$(curl --fail-with-body --silent --show-error \
    "https://api.vgenv.com/v3/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $VGENV_API_KEY") || break
  STATUS=$(printf '%s' "$VIDEO" | jq -er '.status') || break
  printf 'status=%s\n' "$STATUS"
  case "$STATUS" in
    preparing|queued|running) sleep 5 ;;
    succeeded)
      OUTPUT_URL=$(printf '%s' "$VIDEO" | jq -er '.output.url | strings | select(length > 0)') || break
      curl --fail --location --output video.mp4 "$OUTPUT_URL"
      break ;;
    failed|cancelled)
      printf '%s' "$VIDEO" | jq '{id,status,error}'
      break ;;
    *) printf 'Unexpected status: %s\n' "$STATUS" >&2; break ;;
  esac
done
Terminal · Run
bash video.sh

After a request error, resume retrieval with the saved task ID. Python / Node.js examples wait up to 30 minutes; stopping locally does not cancel the task. Adjust this limit for your application. Retry timed-out creation with the original Idempotency-Key and use backoff for 429/503 in production.

V3 ordinary generation enables prompt optimization by default at both 480p and 768p. See the complete request body below to disable it.

01A

Check video status

Already have a jobId? Use it as the Video ID below. Otherwise, create a task with the steps above.

Single retrieval: set VGENV_API_KEY first. Python requires requests; Node.js requires 22+ and an .mjs file.

GET /v3/videos/:videoId
# 替换成创建响应的 id
VIDEO_ID="job_example123"
curl --fail-with-body "https://api.vgenv.com/v3/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $VGENV_API_KEY"

For id job_example123, the full URL is https://api.vgenv.com/v3/videos/job_example123. GET needs no body. Use the creation API key or another valid key in the same Project.

statusMeaningNext step
preparingPreparing, analyzing, or reviewing inputsWait; cancellation allowed
queuedWaiting in the queueWait; cancellation allowed
runningGeneratingKeep polling
succeededSucceeded (terminal)Stop polling and download output.url
failedFailed (terminal)Stop polling and inspect error.code and error.message
cancelledCancelled (terminal)Stop polling

succeeded, failed, and cancelled are separate terminal outcomes. Stop polling on any of them. They are not consecutive steps. Use status to determine completion; progress is for display.

HTTP 200 · Success (key fields)
JSON
{
  "id": "job_example123",
  "status": "succeeded",
  "progress": 100,
  "output": {
    "url": "https://example.com/signed-video.mp4?...",
    "expires_at": "2026-10-10T08:00:00.000Z"
  },
  "error": null
}

HTTP 200 means retrieval succeeded; the task may still be running or may have failed. Download only when status=succeeded and output.url is available. The signed download URL needs no API key and lasts 24 hours; retrieve the task again to refresh it. Results are retained for 30 days, so copy them to your own storage.

Lost the ID? List your tasks

Omit after on the first page. Find the task in the response data array and read its id. When has_more=true, pass next_cursor unchanged as after for the next page. This list contains REST video tasks in the current Project; Studio and standalone upscale tasks are excluded.

Cancel a pending task

Only preparing or queued tasks can be cancelled. Success returns Video JSON with status cancelled and releases the reserved amount. Running or terminal tasks cannot be cancelled here.

Have an ID but cannot retrieve it?

Check the full id, that the key belongs to the creation Project, and that the task was created through REST /videos. Asset IDs, standalone upscale IDs, and Studio Job IDs do not work here. Do not switch to /v1/jobs for REST video retrieval. If the creation response was lost, retry with the original Idempotency-Key and identical request to recover the same task.

Use GET /v3/videos/:videoId for V3, or the matching /v1/videos/:videoId or /v2/videos/:videoId path for an existing integration. status is authoritative: preparing, queued, running, succeeded, failed, or cancelled. Read output.url after success and error after failure.

The created Video includes queue_position and estimated_start_at, but the REST API currently returns null for estimated_start_at. It cannot be used to calculate completion time, and no estimated completion time is returned. queue_position is a changing queue position.

Clients can calculate durations from timestamps: only while queued, subtract queued_at from the current time for this queue round. When started_at is non-null, subtract it from completed_at (or the current time before completion) for elapsed time since the first start. Divide the millisecond difference by 1000, round down, and clamp to zero. Client clock differences can affect live durations. Retries update queued_at but retain the first started_at, so these timestamps do not provide cumulative queue time, GPU active time, or estimated remaining wait.

01B

V1/V2 compatibility

Existing integrations can keep using their current version without migrating to V3.

V1/V2 retain minimax/h3, minimax/h3-human, and minimax/h3-native in requests and responses. V1 defaults to raw and V2 to enhance; new names and endpoints belong to V3.

Save the top-level id from the creation response as VIDEO_ID before querying below. Handle IDs and statuses as with V3.

V1 also supports creation, retrieval by ID, paginated listing, and cancellation. Replace /v2/videos with /v1/videos in these examples. Retrieval and listing cover only REST API Videos in the current Project; only preparing or queued Videos can be cancelled.

The same historical video returns legacy model names through V1/V2 and base, cinematic, or origin through V3. Uploads, balances, and ledger entries continue using the shared /v1 endpoints below.

02

Authentication and safe retries

An API Key belongs to one Project. Its full secret is shown only when created or rotated.

Authorization: Bearer $VGENV_API_KEY

X-API-Key is also accepted, but the standard Bearer header is preferred. This site's API Explorer uses a key you explicitly enter only in current-page memory. Never place secrets in client bundles, URLs, persistent browser storage, or logs.

Idempotency-Key

Strongly recommended for Video creation. This is your request deduplication key, not the returned task ID. Use a new key per new task and keep it for retries; changing parameters with the same key returns 409 IDEMPOTENCY_KEY_REUSED. The API checks for an existing request before importing images or invoking the prompt compiler. Reusing a key for the same normalized request returns the first Video without reserving balance again.

Request format

JSON writes use Content-Type: application/json. Unknown fields are rejected and field names are case-sensitive.

02A

Check balance

Read the available balance of the API key's Project before creating a paid task.

Call GET /v1/credits with a Project API key. V1, V2, and V3 video endpoints share this balance. The request needs no parameters, body, or Idempotency-Key and does not charge the account.

HTTP 200 · Balance response example
JSON
{
  "data": [{
    "projectId": "proj_example123",
    "currency": "CNY",
    "availableMicros": 12500000,
    "reservedMicros": 1500000,
    "spentMicros": 3000000
  }]
}

The data array contains the Project balance in the current market currency. availableMicros is available to spend, reservedMicros is held for pending work, and spentMicros is the settled lifetime spend. Divide micros by 1,000,000 to get the unit named by currency; the example has 12.50 CNY available.

Common uses

Before creating

Read the balance first. For V3, call POST /v3/videos/quote and compare availableMicros with price.amount_micros in the same currency. The creation request still makes the final live balance check.

Track holds and settlement

Read again after creation: paid work can reduce available balance and increase the held amount. On success, the hold becomes settled spend; failure or cancellation releases it according to the final billing result.

Handle insufficient balance

If creation returns HTTP 402, refresh availableMicros and the quote before retrying. A prior balance snapshot does not prove that a charge succeeded.

03

Video request and response

The REST API is always paid, private, and watermark-free; clients do not submit those internal policies.

FieldTypeRules
modelstringModel: base (Base), cinematic (Cinematic), origin (Origin, authorization required)
turboboolean?Defaults to false; requires separate authorization and an enabled runtime. Actual Turbo adds 30% to generation, with no multiplier on upscale fees.
tierfast | standard | enhanced | quality?Four generation tiers independent of the base model; defaults to fast
combat_enhancementboolean?Enables combat enhancement; defaults to false. Check model capabilities and the quote for availability.
motion_speedinteger?Allowed only with combat enhancement enabled; integer from -10 to 10, defaulting to 3 when enabled.
creation_intentperson_replacement?Omit for ordinary generation; person_replacement enables person replacement
promptstring?Required for ordinary generation: 5–30000 Unicode characters after trimming. Optional or empty for replacement; supplied text adds instructions, up to 2000 characters
motion_start_secondsnumber?Replacement only, nonnegative, default 0; motion and preserved audio share this window
seedinteger?0–281474976710654; generated and returned by the server when omitted, for reproducible randomness
prompt_optimizationobject?Ordinary generation: mode enhance/raw, default raw in V1 and enhance in V2/V3 at both 480p and 768p. Pass mode: raw to disable optimization. Replacement always analyzes media in all three versions; explicit raw returns 422 PERSON_REPLACEMENT_ANALYSIS_REQUIRED.
durationinteger?Ordinary generation supports 2–15 seconds at 768p and 4–15 seconds at 480p and uses the server default when omitted. Replacement defaults to floor(min(video duration - motion_start_seconds, 15)), at least 2 seconds; explicit duration must fit the remaining source video
resolution480p | 768p?A resolution tier, not fixed pixel dimensions; replacement requires and defaults to 768p
upscalenone | 2x?Request 2x output upscaling for ordinary generation; defaults to none. Check capabilities and quotes for availability and added cost. Unsupported for replacement
aspect_ratiostring?Portrait 9:16, 2:3, 3:4; square 1:1; landscape 4:3, 3:2, 16:9, or 21:9; defaults to portrait 9:16
image_urlstring?Public HTTPS URL for the first frame. Omit frame_images when using this field.
reference_image_urlsstring[]?Ordered public HTTPS URLs for 1–9 reference images. Omit reference_images when using this field.
frame_imagesarray?JPEG/PNG/WebP Data URLs or public HTTPS URLs with frame_type first_frame or last_frame
reference_imagesarray?Up to nine images for ordinary generation; exactly one character image for replacement. Data URL/public HTTPS; available Base tiers can combine these with one first_frame. Reference numbering starts at 1
reference_videoobject?A ready MP4 Asset: { asset_id }; at most one, with or without audio, combinable with reference images and audio but not image_url or frame_images; preserving source audio requires an audio stream
preserve_source_audioboolean?Default false for ordinary generation and true for replacement. Reuses reference_video audio; replacement crops it to the motion window. Disabling it for replacement removes source audio and does not promise newly generated sound
reference_audiosobject[]?Ordinary generation: 1–2 ready MP3/WAV Assets in Audio 1/2 order; mutually exclusive with reference_audio
audio_guideobject?First/last-frame audio guide: {asset_id}, MP3/WAV up to 50 MiB, greater than 0 and up to 15 seconds, mono/stereo at 8–96 kHz. Requires explicit model capability; incompatible with reference media. Original soundtrack and lip synchronization are not guaranteed.
reference_audioobject?Ordinary generation only: one ready MP3/WAV Asset; unsupported for replacement

Disable prompt optimization: complete request body

Submit the following ordinary text-to-video body to POST /v3/videos. Set prompt_optimization.mode = raw to disable optimization and use the submitted prompt. Omitting the object or its mode defaults to enhance in V3 at both 480p and 768p.

POST /v3/videos · Complete body with optimization disabled
JSON
{
  "model": "base",
  "tier": "standard",
  "prompt": "海边日落,一位穿着白色长裙的成年女性沿沙滩缓缓行走,海风吹动裙摆,镜头平稳跟随,伴随自然海浪声。",
  "duration": 5,
  "resolution": "768p",
  "aspect_ratio": "9:16",
  "seed": 42,
  "prompt_optimization": {
    "mode": "raw"
  }
}

For 480p, change only resolution to 480p and keep mode: raw; the 5-second duration works at both resolutions. You may omit seed to let the server generate it. Send Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. If using Idempotency-Key, use a new value for each new task and keep it for retries of the same request.

Person replacement (creation_intent: person_replacement) requires media analysis and cannot disable it. Passing raw returns 422 PERSON_REPLACEMENT_ANALYSIS_REQUIRED.

Creation and retrieval return a Video object directly, as below; only lists wrap items in a data array. price.amount_micros is an integer: 1 CNY/USD = 1,000,000 micros, so 150,000 CNY micros = ¥0.15. The actual server quote determines the price.

Show the full Video response
Video · JSON
JSON
{
  "id": "job_example123",
  "object": "video.generation",
  "model": "base",
  "tier": "fast",
  "status": "queued",
  "duration": 15,
  "seed": 42,
  "resolution": "480p",
  "aspect_ratio": "9:16",
  "preserve_source_audio": false,
  "progress": 0,
  "tags": [],
  "queue_position": 3,
  "estimated_start_at": null,
  "price": { "currency": "CNY", "amount_micros": 150000 },
  "output": null,
  "error": null,
  "prompt_optimization": { "mode": "raw", "route": null, "applied": false },
  "queued_at": "2026-08-20T01:02:03.000Z",
  "started_at": null,
  "completed_at": null,
  "created_at": "2026-08-20T01:02:03.000Z",
  "updated_at": "2026-08-20T01:02:03.000Z"
}
Show the paginated list response
Video list · JSON
JSON
{
  "object": "list",
  "data": [{
    "id": "job_example123",
    "object": "video.generation",
    "model": "base",
    "tier": "fast",
    "status": "succeeded",
    "duration": 15,
    "seed": 42,
    "resolution": "480p",
    "aspect_ratio": "9:16",
    "progress": 100,
    "tags": ["cinematic"],
    "queue_position": null,
    "estimated_start_at": null,
    "price": { "currency": "CNY", "amount_micros": 150000 },
    "output": { "url": "https://…", "expires_at": "2026-08-21T01:02:03.000Z" },
    "error": null,
    "prompt_optimization": { "mode": "enhance", "route": "text", "applied": true },
    "queued_at": "2026-08-20T01:00:00.000Z",
    "started_at": "2026-08-20T01:00:30.000Z",
    "completed_at": "2026-08-20T01:02:03.000Z",
    "created_at": "2026-08-20T01:00:00.000Z",
    "updated_at": "2026-08-20T01:02:03.000Z"
  }],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkQXQiOiIuLi4iLCJpZCI6ImpvYl8uLi4ifQ"
}
Task timing fieldMeaning
created_atTime the Video was created.
queued_atUpdated on entry to the generation queue. While preparing, it may contain an initial creation-time value and does not mean the video is queued yet.
queue_positionCurrent queue position, meaningful only while queued; it can change or be null.
started_atFirst execution start time; null before execution and retained across retries.
completed_atTime the Video reached succeeded, failed, or cancelled; null beforehand.
updated_atLast record update, not completion time. duration is output video length, not execution time.

An accepted video returns HTTP 202 with the same Job ID in id and job_id and an initial status of preparing. Both modes review the original prompt and prepare inputs. Raw uses the reviewed prompt directly. Enhance also optimizes it. After a review rejection, polling returns HTTP 200 with status failed and error code NSFW_CONTENT_DETECTED. If the enhanced prompt is too short or too long, generation uses the reviewed original and prompt_optimization.applied is false. While waiting for inputs, preparation_stage is inputs. A rejected review or another terminal optimization error sets the status to failed and releases the reservation. Replacement also analyzes and reviews while preparing and alone returns creation_intent and motion_start_seconds. Preparing and queued videos may be cancelled.

The list contains only Videos created through the REST API in the current Project and is ordered by created_at then id, newest first. limit defaults to 20 and ranges from 1 to 100; pass the prior page's opaque next_cursor as after. queue_position is dynamic and may change or be null; estimated_start_at is currently null in the REST API, and only status is authoritative. On succeeded, output.url and output.expires_at are available. REST API download URLs last 24 hours; retrieve the detail or list again after URL expiry. REST API results are retained for 30 days, then deleted automatically and cannot be restored by querying again. Copy them to your own storage before expiry.

03A

Combat enhancement and motion speed

Enable combat enhancement in a video creation request and adjust the generated motion.

Set combat_enhancement: true and optionally provide an integer motion_speed from -10 to 10; it defaults to 3 when enabled. Motion speed controls generated motion, not video playback speed. Omit motion_speed when combat enhancement is disabled or omitted.

Call GET /v3/models first and check that configurations[].combat_enhancement is true for the selected model, tier, and inputs. If also requesting Turbo, combat_turbo must be true. Capability discovery does not reserve capacity; use the quote and creation response for actual availability.

Submit this body to POST /v3/videos/quote first, then to POST /v3/videos to create. Creation reserves funds; use an Idempotency-Key. Quotes and Video responses include both fields when enabled and omit them when disabled. V1/V2 accept the same fields with their corresponding minimax/h3 model names.

Combat enhancement · V3 request body
JSON
{
  "model": "base",
  "tier": "standard",
  "prompt": "Two martial artists spar in a bright training hall.",
  "duration": 4,
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "combat_enhancement": true,
  "motion_speed": 3
}
03B

Models and quotes

Base, Cinematic, and Origin use separate model IDs; choose the tier and Turbo independently.

GET /v3/models returns only published models and input configurations authorized for the API key creator. Configurations include tiers, modes, role counts, duration, resolution, aspect ratios, generation-time upscale, and Turbo eligibility. Origin and Turbo require separate permissions; combining them requires both. Keys without a creator identity cannot obtain these permissions.

POST /v3/videos/quote accepts the same fields and defaults as creation. It returns video.quote, selected settings, and price.currency / amount_micros / unit_price_micros / catalog_version. Quoting creates no job, reserves no balance, runs no prompt or replacement analysis, and imports no remote images. Image roles determine configuration; content and downloadability are checked on creation. Uploaded media still require Project access, readiness, audio-track checks, and valid motion windows.

turbo_requested records the request; turbo records the actual choice at quote or creation. Discovery reserves no capacity. Busy compatible capacity queues work; confirmed lack of supply may select standard pricing before creation. Observation and authentication failures are errors. Supply may change after a quote; creation rechecks and returns the final price. Accepted jobs are not upgraded, repriced, or switched to another model.

Origin 768p test prices per second are 0.03 / 0.05 / 0.08 / 0.10 CNY for fast / standard / enhanced / quality, or 0.0045 / 0.0075 / 0.012 / 0.015 USD. 480p is half price. Check discovery and quotes for available replacement and generation-time 2x combinations. Enhanced and person replacement do not support generation-time 2x. Completed output may be upscaled separately. Omitting turbo keeps standard pricing; V1 defaults to raw, V2 to enhance, and tier to fast.

03C

Speech generation

Generate standalone speech from text using an authorized reference voice.

  1. Follow Media input to upload and complete a reference voice, then use its asset.id from the same Project. MP3/WAV up to 50 MiB and 15 seconds, mono/stereo at 8–96 kHz. Confirm you are authorized to use the voice.
  2. POST {"max_duration_seconds": 10} to /v3/audio/generations/quote to obtain the currency, price catalog version, and maximum reservation. Quoting does not create a task or reserve funds.
  3. POST the reference asset ID, text, voice_consent: true, and the same duration limit to /v3/audio/generations. Optionally pass the quoted currency, version, and maximum amount as price_limit. Creation reserves funds; save the returned speech_... ID and idempotency key.
  4. Poll GET /v3/audio/generations/:speechId, then download result.wav_url or result.flac_url after success. Signed download URLs need no API key. Results are retained for 30 days; retrieve again to refresh expired URLs during that period.

Before creating a speech task or reserving funds, the server reads the reference file metadata. A duration over 16 seconds returns 422 SPEECH_REFERENCE_DURATION_EXCEEDED; unreadable metadata returns 422 SPEECH_REFERENCE_METADATA_INVALID. The 16-second threshold allows for metadata error only. The audio is fully validated before execution; an actual duration over 15 seconds fails the task and releases the reservation. API clients should trim the reference audio themselves.

Text must not be blank and is limited to 200 Unicode characters. max_duration_seconds is an integer from 1 to 15; audio exceeding the limit fails rather than being truncated. The maximum is reserved first and actual audio duration is charged on success; failure or cancellation releases the reservation. Creation requires a Project API key with a creator identity; legacy keys without one cannot create tasks.

Continue polling while status is queued, running, or verifying; succeeded, failed, and canceled are terminal. GET /v3/audio/generations returns up to 20 items; pass next_cursor as the next cursor. Cancel unfinished tasks with DELETE /v3/audio/generations/:speechId.

The upload example requires VGENV_API_KEY, VOICE_FILE, and VOICE_CONTENT_TYPE (audio/wav for WAV or audio/mpeg for MP3). Set the returned VOICE_ASSET_ID and an IDEMPOTENCY_KEY, then run the quote, create, poll, and download example. Bash needs curl/jq, Python needs requests, and Node.js needs 22+. Use a new key for each new task; retry a timeout with the same body, asset ID, and key. Stopping locally does not cancel the task.

The generation examples save speech-request.json without overwriting an existing file. If creation times out, retry creation only with the saved body and original IDEMPOTENCY_KEY; do not upload again or replace the parameters after requoting. Bash retry:

POST /v3/audio/generations · retry
Bash
curl --fail-with-body https://api.vgenv.com/v3/audio/generations \
  -H "Authorization: Bearer $VGENV_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @speech-request.json

Optional: language, speed, and emotion

To use advanced settings, include the object below as settings in the creation request; every field is required when it is supplied. language accepts zh / en / ja / es / ar, speed ranges from 0.5 to 2.0, and emotion strength from 0 to 1. Check the current OpenAPI for availability; omit settings when not needed.

emotion.mode accepts default / auto / reference / description / fine. Only description mode uses a nonblank description of up to 100 characters without control characters or < > |; other modes require an empty string. Only fine mode accepts choice: happy / angry / sad / afraid / disgusted / low / surprised / neutral; other modes require null.

Standalone speech · settings object
JSON
{
  "version": 1,
  "language": "zh",
  "speed": 1.25,
  "emotion": {
    "mode": "fine",
    "strength": 0.8,
    "description": "",
    "choice": "happy"
  }
}
03D

Standalone output upscale

Create a separate 2x output for a succeeded Video, preserving the original and charging only for upscale.

Use a succeeded REST Video in the same Project whose output is readable and has not been upscaled. Quote eligibility and price via POST /v3/video-upscales/quote, then create via POST /v3/video-upscales to receive HTTP 202 and a separate video.upscale resource. Both accept video_id and scale=2x; creation supports Idempotency-Key. Even for Origin sources, only upscale is charged: 0.01 CNY or 0.0015 USD per second at 480p; 0.02 CNY or 0.003 USD at 768p. No Turbo or repeated generation is used.

Query /v3/video-upscales/:upscaleId or DELETE it to cancel a queued upscale. Failure or cancellation releases the reservation. Successful output follows the same URL expiry and retention rules as REST Videos. Standalone upscales are excluded from /v1/videos and /v3/videos lists and never replace the source. Existing generation-time upscale=2x calls remain compatible.

04c

External video upscale

Upscale your own uploaded video using asset_id, separately from platform-generated video upscales that use video_id.

Available now: upload and confirm your video with a project API key, then quote, create, and retrieve using the steps below. Videos enter the upscale queue only after passing content review.

Integration steps

  1. Follow Media input below: create /v1/assets/uploads, PUT the MP4 to the signed URL with all returned upload headers, then POST /v1/assets/:assetId/complete. Save the ready asset ID in the same Project.
  2. Use a Project API key to POST /v3/external-video-upscales/quote with {asset_id, scale: '2x'}. A quote does not reserve funds or approve content.
  3. POST the same payload to /v3/external-video-upscales to receive HTTP 202 and an external_video.upscale resource. Creation reserves funds; video review runs during preparing, after upload confirmation and before upscale execution. Approved tasks proceed through queued → running → succeeded.
  4. Save the returned id and GET /v3/external-video-upscales/:id. Poll every 5 seconds and stop on succeeded, failed, or cancelled; back off on network errors or 429. Read output.url on success and error.code on failure. There is no DELETE endpoint; these tasks do not appear in /v3/videos lists.

Pricing and output dimensions

Input short edgeCNY / secondOutput short edge
480p0.02960 px
768p0.031536 px

CNY only, billed by actual milliseconds. price.amount_micros is an integer in micro-yuan (1 CNY = 1,000,000 micros); use the server quote. Both dimensions double, preserving source frame rate and audio presence. 1K / 2K do not mean fixed 1080p / 1440p; read output_width / output_height for exact dimensions. Review rejection or task failure releases reserved funds; success settles the charge.

Input limits

MP4 / H.264, constant 24, 25, or 30 fps, 2–60 seconds, at most 200 MiB. The short edge must be 480 or 768 pixels, with the long edge at most 864 or 1376 pixels respectively; both dimensions must be even.

Also satisfy the total pixel-frame limit: width × height × ceil(duration_ms × fps / 1000) ≤ 1376 × 768 × 24 × 15. At 1376×768, this allows at most 15 seconds at 24 fps or 12 seconds at 30 fps; the 60-second ceiling does not apply to every configuration. Over-limit inputs are rejected, never automatically trimmed or downgraded.

Creation supports Idempotency-Key: identical requests with the same key return the original task; changed parameters conflict. Use a new key for a new attempt after failure. queue_position is null; no live queue rank is provided. output is null before success.

Examples require a confirmed ASSET_ID. Bash requires jq, Python requires requests, and Node.js requires 22+. Examples retrieve once; follow the terminal-state rules above for repeated polling.

Common errors

EXTERNAL_UPSCALE_DISABLED · Submissions unavailable; do not retry continuously.
EXTERNAL_UPSCALE_SPEC_UNSUPPORTED / EXTERNAL_UPSCALE_FRAME_BUDGET_EXCEEDED · Adjust video specifications or duration.
EXTERNAL_UPSCALE_SOURCE_CHANGED · Source changed; upload and confirm again.
NSFW_CONTENT_DETECTED / VIDEO_REVIEW_UNAVAILABLE · Content rejected or review unavailable; failed tasks release reserved funds.

04

Person replacement

Use a Project API key to submit one character image and one motion video. No separate allowlist or prompt-generation call is required. These examples use V3; media and configuration requirements still apply.

Set creation_intent: person_replacement, provide one identity image via reference_images or reference_image_urls and a ready reference_video.asset_id. All four tiers use 768p. image_url, frame_images, reference_audio, reference_audios, audio_guide, and 2x are unsupported. Source audio is preserved by default and requires an audio stream. Videos without audio are accepted when preserve_source_audio=false. Omit prompt unless you want to add instructions, up to 2000 characters.

By default, start at zero and use the remaining source duration rounded down, capped at 15 seconds. Set motion_start_seconds and an integer duration from 2 to 15 to choose a window that fits entirely within the source. Source audio is preserved for that window by default. Creation returns 202 with preparing; media analysis and review run before queued. Failed preparation or cancellation releases reserved balance and exposes error details. Unanalyzed instructions are never sent directly to generation.

tierCNY / secondUSD / second
fast¥0.04$0.0062
standard¥0.05$0.0077
enhanced¥0.08$0.012
quality¥0.10$0.015

USD reference prices are converted from CNY at 1 USD = 6.5 CNY. The server's currency and price snapshot determine the actual charge.

The three steps switch languages together. Bash requires jq; Python requires requests and all steps in one .py file; Node.js 22+ requires all steps in one .mjs file. Set VGENV_API_KEY in your environment and prepare motion.mp4 with an audio stream plus a public character image URL. Preserve the Idempotency-Key when retrying creation; use a new key when changing inputs or options.

05

Media input

Images can be submitted directly as JPEG, PNG, or WebP Data URLs or public HTTPS URLs in frame_images or reference_images. Reference video and audio must first be created and confirmed as Project Assets, then supplied by asset_id in the Video request.

Each image may be up to 5 MiB, with no separate aggregate image-size limit. Oversized Data URLs are rejected from their Base64 length before decoding. When an HTTPS source declares Content-Length, it is rejected before downloading the body; otherwise the API reads at most 5 MiB and aborts as soon as another byte is received. HTTPS images must be publicly reachable. Private, loopback, link-local, credential-bearing, or unsafe redirect targets, non-image content, and downloads exceeding 10 seconds are rejected.

The image example also returns a top-level id; retrieve it as shown in Quickstart. Add a last_frame item to frame_images for first/last-frame generation. For references alone, use reference_images or reference_image_urls. To also set a start image, see below.

Start image with reference images

Use this body for POST /v3/videos/quote or POST /v3/videos. The start image is separate from numbered subject or scene references. Base supports Fast, Standard, Enhanced and Quality wherever the configuration is active. Use standard speed, no upscaling, one start image and 1–9 reference images.

Choose either form for each role independently. Supplying both forms for the same role returns 400 VIDEO_IMAGE_FIELDS_CONFLICT. A null shorthand field is treated as omitted. The quote checks the input combination. Remote images are downloaded and validated during creation.

{
  "model": "base",
  "tier": "standard",
  "prompt": "A woman walking on the beach",
  "image_url": "https://example.com/start.jpg",
  "reference_image_urls": [
    "https://example.com/person.jpg"
  ]
}

Reference video

One MP4, up to 200 MiB, with or without audio. The API requires an audio stream only when source audio preservation is requested; a missing stream then returns 422 REFERENCE_VIDEO_AUDIO_TRACK_REQUIRED. Reference it with reference_video.asset_id after upload. All tiers support 2–15 second output duration at 768p and 4–15 seconds at 480p. This limits output duration, not the uploaded reference-video duration.

Preserve the reference video's original audio

After uploading and completing an MP4 with an audio stream, set preserve_source_audio: true. With either enhance or raw prompt optimization, the final soundtrack comes directly from reference_video, replacing all generated speech, music, and effects. Additional reference_audio may still condition generation but does not become the delivered soundtrack.

Uses the source video's first audio stream, starting at zero for ordinary generation or motion_start_seconds for replacement and preserving its start offset. Longer audio is truncated to the actual output length at encoded packet boundaries; shorter audio ends naturally. No looping, stretching, padding, or mixing is applied, and generated lip movements may differ. Pricing is unchanged, and generation followed by 2x delivers the same source soundtrack. Creation and query responses include preserve_source_audio; use a new Idempotency-Key when changing it.

Reference audio

MP3 or WAV, up to 50 MiB per track. reference_audios accepts up to two tracks; reference_audio is the legacy single-track form, and the two fields are mutually exclusive. Use audio_guide below for frame-image generation, without reference-media fields.

Reference video and audio: upload, confirm, create a Video

The steps show each request: upload and complete the video and audio separately, then pass both returned asset.id values to creation. If copying individual steps, carry the IDs across manually; expand the complete script to run the full flow. The default files are reference.mp4 (video/mp4) and reference.mp3 (audio/mpeg); use audio/wav for WAV. Save it as media.sh for Bash, install requests and save it as media.py for Python, or use media.mjs with Node.js 22+. The script prints the Video ID for status retrieval.

GET /v1/assets/:assetId checks an Asset's status and refreshes its short-lived download URL. DELETE /v1/assets/:assetId deletes a Project Asset and returns 204 on success. Media used by preparing, queued, or running jobs cannot be deleted. Use the image URL fields above for images. Asset IDs are not accepted as image URLs.

05A

Frame images + audio guide

Guide video generation with audio and a first frame, last frame, or both. Use POST /v3/videos; no separate endpoint or mode field is needed.

  1. Use the same Project API key for POST /v1/assets/uploads, then PUT the MP3/WAV to the signed URL with all returned upload headers. Do not send the API key to the upload URL.
  2. Call POST /v1/assets/:assetId/complete, verify status=ready, and save the asset ID. Assets from another Project cannot be used directly.
  3. Use image_url for a start image or frame_images for frame roles, together with audio_guide: {asset_id}. Save the top-level id, retrieve it with GET /v3/videos/:videoId, and download output.url after success.
Input combinationframe_images
First frame + audioframe_type: first_frame
Last frame + audioframe_type: last_frame
First/last frames + audioTwo items, one first_frame and one last_frame

Use one MP3/WAV up to 50 MiB, greater than 0 and up to 15 seconds, mono or stereo at 8–96 kHz. Audio may be shorter or longer than the output without changing the requested duration. duration is an integer: 2–15 seconds at 768p or 4–15 at 480p. Actual video length follows frame alignment; for example, the 5-second option is about 5.17 seconds.

Supports published base / cinematic / origin configurations and all four tiers. Turbo and 2x retain the model's restrictions; check GET /v3/models and the quote. Audio guidance adds no separate fee. Do not combine it with reference_image_urls, reference_images, reference_video, reference_audio, reference_audios, or person replacement.

Audio guidance differs from source-audio preservation

audio_guide conditions generated sound and images; it does not copy the uploaded track into the result or guarantee identical voices or exact lip synchronization. Do not set preserve_source_audio=true for this purpose; use reference_video above to preserve its original soundtrack. Omitting audio_guide removes guidance and does not mute the generated video.

The payload below uses both frames; remove either item for first-only or last-only input. The complete scripts read VGENV_API_KEY, IDEMPOTENCY_KEY, and FIRST_FRAME_URL / LAST_FRAME_URL from the environment and default to guide.wav. For MP3, set AUDIO_CONTENT_TYPE=audio/mpeg. The examples explicitly use raw; V3 defaults to enhance if omitted.

Creation reserves funds. Scripts save audio-guide-request.json and print the asset and Video IDs. If creation times out, retry only that step with the same payload, asset IDs, and Idempotency-Key; do not upload again and substitute a new asset ID. Changing audio or frames creates a different request and requires a new key. V1/V2 also accept audio_guide with minimax/h3, minimax/h3-human, or minimax/h3-native model names.

06

Public endpoints

Base URL · https://api.vgenv.com

GET/v3/models

Read published model configurations authorized for this API key.

POST/v3/videos/quote

Quote a V3 request; creation returns the final price.

POST/v3/audio/generations/quote

Quote standalone speech without creating a task.

POST/v3/audio/generations

Create a speech task from a reference voice and text.

GET/v3/audio/generations

List the current Project's speech tasks with a cursor.

GET/v3/audio/generations/:speechId

Retrieve speech status and download URLs.

DELETE/v3/audio/generations/:speechId

Cancel an unfinished speech task.

POST/v3/external-video-upscales/quote

External video upscale quote.

POST/v3/external-video-upscales

Create external upscale; review before queueing.

GET/v3/external-video-upscales/:id

Retrieve external upscale state and output.

POST/v3/video-upscales/quote

Quote standalone 2x for a succeeded REST Video.

POST/v3/video-upscales

Create a standalone upscale and reserve only the upscale fee.

GET/v3/video-upscales/:upscaleId

Read standalone upscale state and output.

DELETE/v3/video-upscales/:upscaleId

Cancel a queued upscale and release its reservation.

GET/health

Deployment readiness check; returns non-2xx when a required dependency fails.

GET/v1/status

Read the live state of the API, PostgreSQL, and asset storage.

POST/v1/assets/uploads

Create a Project Asset direct-upload request and receive an Asset plus an expiring PUT URL.

POST/v1/assets/:assetId/complete

Confirm a direct upload; only a ready Asset can be used as video or audio reference.

GET/v1/assets/:assetId

Read a Project Asset's status and short-lived download URL.

DELETE/v1/assets/:assetId

Delete a Project Asset unless an active job uses it.

POST/v3/videos

Create a video; prompt optimization and replacement analysis run asynchronously while preparing.

POST/v2/videos

V2 retains legacy model names and defaults to enhance.

POST/v1/videos

V1 ordinary generation defaults to raw; person replacement uses automatic analysis as in V2.

GET/v2/videos

List this Project's REST API Videos with legacy model names using a cursor.

GET/v2/videos/:videoId

Retrieve a V2 Video's status, output, or failure.

DELETE/v2/videos/:videoId

Cancel a preparing or queued Video.

GET/v1/videos

List this Project's REST API Videos with legacy model names using a cursor.

GET/v1/videos/:videoId

Retrieve a V1 Video's status, output, or failure.

DELETE/v1/videos/:videoId

Cancel a preparing or queued Video.

GET/v3/videos

List REST API Videos in the current Project with cursor pagination.

GET/v3/videos/:videoId

Read queue position, progress, result, or failure.

DELETE/v3/videos/:videoId

Cancel a preparing or queued Video and release its reserved balance.

GET/v1/credits

Read available, reserved, and spent balance.

GET/v1/credits/ledger

List the Project's auditable balance entries.

Health and Status require no API key; every other endpoint requires a Project API Key. A degraded Status document still returns 200; use Health for deployment readiness. The /v1/jobs route used by the APP, account, payment, and internal Worker endpoints are outside the public ToB OpenAPI.

07

HTTP errors

Non-2xx responses use JSON. message can be a string or an array of field-validation messages.

HTTPMeaningHandling
400Bad RequestInvalid fields, Data URL, or public HTTPS image.
401UnauthorizedMissing, revoked, or invalid API Key.
402Payment RequiredThe Project has insufficient balance.
403ForbiddenThe authenticated identity cannot perform the operation.
404Not FoundThe Video or Asset does not exist in this Project.
409ConflictThe idempotency key belongs to another request, or resource state conflicts.
413Payload Too LargeAn individual input image exceeds 5 MiB.
422Unprocessable EntityThe model, tier, duration, resolution, aspect ratio, or input combination has no execution route.
429Too Many RequestsA request limit has been reached. Retry after a delay.
503Service UnavailableA required dependency, such as object storage, is temporarily unavailable.

Stable application error codes

codeMeaning
AUDIO_GUIDE_INPUT_INVALIDAudio guidance requires frame images; check duplicate frame types and conflicting reference-media fields.
AUDIO_GUIDE_INVALIDUse a fully decodable MP3/WAV of up to 15 seconds, mono/stereo, at 8–96 kHz.
AUDIO_GUIDE_UNAVAILABLEAudio guidance is unavailable; check models or quote again. Do not silently remove audio and retry.
NATIVE_MODEL_NOT_AVAILABLEThe API key creator is not authorized for Origin.
TURBO_NOT_ALLOWEDThe API key creator is not authorized for Turbo.
TURBO_UNAVAILABLEThe signed Turbo configuration is unavailable.
EXECUTION_RECIPE_UNAPPROVEDNo accepted standard execution plan exists for this configuration.
EXECUTION_UPSCALE_UNAPPROVEDNo accepted standalone upscale execution plan exists.
NATIVE_CONFIGURATION_UNSUPPORTEDThe requested Origin model and tier combination is unsupported.
UPSCALABLE_VIDEO_REQUIREDUse a succeeded, readable REST Video in the same Project that has not been upscaled.
BAD_REQUESTInvalid fields, product rules, balance, or Asset metadata.
IDEMPOTENCY_KEY_INVALIDIdempotency-Key is empty, too long, or contains non-visible/non-ASCII bytes.
IDEMPOTENCY_KEY_REUSEDThe Idempotency-Key is already bound to a different create request in this Project.
UNSUPPORTED_CONFIGURATIONThe requested model, tier, duration, resolution, aspect-ratio, or input combination is not currently available.
PERSON_REPLACEMENT_ANALYSIS_REQUIREDReplacement requires media analysis. Omit prompt_optimization or use enhance; raw is not supported.
PERSON_REPLACEMENT_INPUT_INVALIDReplacement requires exactly one character image and one motion video, with no frame images or reference audio.
PERSON_REPLACEMENT_CONFIGURATION_UNSUPPORTEDReplacement supports only 768p with upscale set to none.
PERSON_REPLACEMENT_INTENT_REQUIREDmotion_start_seconds requires creation_intent=person_replacement.
PERSON_REPLACEMENT_PREPARATION_UNAVAILABLEAutomatic preparation is unavailable. Creation returns 503; retry later with the same Idempotency-Key.
MOTION_WINDOW_EXCEEDS_SOURCEThe motion window extends beyond the source video. Reduce duration or adjust motion_start_seconds.
VIDEO_DURATION_MUST_BE_2_TO_15_SECONDS768p duration must be an integer from 2 to 15; replacement requires at least 2 seconds remaining in the source.
VIDEO_DURATION_MUST_BE_4_TO_15_SECONDS480p duration must be an integer from 4 to 15.
REFERENCE_VIDEO_AUDIO_TRACK_REQUIREDSource audio preservation was requested but reference_video has no audio stream. Supply a video with audio or disable preserve_source_audio.
SOURCE_AUDIO_REQUIRES_REFERENCE_VIDEOEnabling preserve_source_audio without reference_video returns HTTP 422 at creation.
SOURCE_AUDIO_PRESERVATION_FAILEDSource-audio validation or muxing failed. The asynchronous task reports status=failed with this error.code; generated audio is not substituted.
FRAME_IMAGE_URL_UNSUPPORTEDThe image is not a supported JPEG, PNG, or WebP Data URL.
REMOTE_IMAGE_URL_INVALID / REMOTE_IMAGE_URL_UNSUPPORTEDThe remote image URL is invalid, is not HTTPS, or contains credentials.
REMOTE_IMAGE_HOST_FORBIDDEN / REMOTE_IMAGE_DNS_FAILEDThe remote host cannot be resolved, or its DNS answers contain a private, loopback, link-local, reserved, or otherwise restricted target.
REMOTE_IMAGE_REDIRECT_INVALID / REMOTE_IMAGE_REDIRECT_LOOP / REMOTE_IMAGE_TOO_MANY_REDIRECTSThe remote image has an invalid, unsafe, looping, or more than three redirects.
REMOTE_IMAGE_FETCH_FAILED / REMOTE_IMAGE_TIMEOUTThe remote image could not be reached, or the import including DNS, redirects, and download exceeded 10 seconds.
REMOTE_IMAGE_CONTENT_ENCODING_UNSUPPORTED / REMOTE_IMAGE_CONTENT_TYPE_UNSUPPORTED / REMOTE_IMAGE_EMPTYThe remote response is compressed, empty, or is not a supported JPEG, PNG, or WebP image.
INPUT_IMAGE_TOO_LARGE / REMOTE_IMAGE_TOO_LARGEAn individual input image exceeds 5 MiB. There is no additional aggregate image-size limit.
REMOTE_IMAGE_SIGNATURE_INVALIDThe remote image's declared type does not match its file signature.
ASSET_IN_USEThe Asset is referenced by a preparing/queued/running Job and cannot be deleted.
PROJECT_ACTIVE_JOB_LIMIT_EXCEEDEDThe Project has reached its queued/running Job limit.
VIDEO_CURSOR_INVALIDThe Video list cursor is invalid or corrupted.
QUEUE_TIMEOUTThe Video exceeded the maximum queue wait; it failed and its reserved balance was released.
UNAUTHORIZEDThe API Key is missing, invalid, expired, or revoked.
NOT_FOUNDThe resource does not exist in the current Project.
CONFLICTThe resource's current state does not allow the operation.
RATE_LIMITEDA request or Project activity limit was reached; retry after Retry-After.
SERVICE_UNAVAILABLEA required dependency is temporarily unavailable.
Error · JSON
JSON
{
  "statusCode": 422,
  "code": "UNSUPPORTED_CONFIGURATION",
  "message": "The requested video configuration is not currently available",
  "details": {
    "requested": { "model": "base", "duration": 15, "resolution": "768p", "aspect_ratio": "2:3", "mode": "t2va" },
    "availableConfigurations": [{
      "duration": { "min": 2, "max": 15, "default": 15 },
      "resolutions": ["768p"],
      "aspect_ratios": ["9:16", "2:3", "3:4", "1:1", "4:3", "3:2", "16:9", "21:9"]
    }]
  },
  "requestId": "req-…"
}
HTTP errors differ from asynchronous failures

HTTP 202 means the request was accepted, not that generation completed. Asynchronous failures set status to failed and provide error.code and error.message.

08

Limits, billing, and retries

Understand job billing, concurrency limits, and safe retries.

base480p · 768presolution tiers
Duration768p: 2–15s / 480p: 4–15sinteger seconds
Billing480p half price768p base price
Per image5 MiBJPEG · PNG · WebP
Currently creatable combinations

base supports text-to-video, first/first-last-frame keyframe generation, and reference generation with images, video, and audio. Available combinations are determined by active profiles; unvalidated models or combinations return 422 UNSUPPORTED_CONFIGURATION, with available input roles in details.availableConfigurations.

  • Video creation reserves the final server quote; success settles it and platform failure releases it.
  • Clients cannot select billing currency. Domestic deployments use CNY; global deployments use USD.
  • GET requests and POST /videos with Idempotency-Key are safe to retry. Use exponential backoff with jitter for 429/503.
  • We no longer impose a fixed concurrency cap on paid generation jobs. You can submit multiple jobs using one account and one API key. We scale up GPU capacity as much as possible, but limited compute availability during peak periods can lead to queue times of 10–30 minutes. We aim to keep peak-time waits under 15 minutes by adding more GPUs, though wait times are not guaranteed. Peak periods are typically daytime on Thursdays and Fridays in the Asia-Pacific region.
  • A REST API Video may remain queued for up to 24 hours by default; QUEUE_TIMEOUT then fails it and automatically releases the reservation.
  • 429 responses include Retry-After plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Login uses a persistent cross-instance limit by IP and email.
  • Video Webhooks are not available yet. V3 clients can poll GET /v3/videos/:videoId; the V1 path remains compatible.
09

Safety, rights, and data handling

API key holders are responsible for prompts, media, and generated uses submitted under their Project.

Submit only content you may lawfully process

Do not submit illegal content, child sexual exploitation material, unauthorized private or biometric data, infringing media, or use the service for fraud, harassment, impersonation, or safety-control evasion. The service may reject requests, restrict Projects, or revoke API keys.

API use is subject to the Terms and Privacy Policy. Domestic and global deployments may use different data regions, payment providers, and billing currencies. Customers must assess lawful handling of cross-border or regulated data before integration. Never place API keys, signed URLs, or user content in client bundles or public logs.