Generation

Generate a video

Changed on

Create a video generation job. Handles text-to-video, image-to-video (send a start frame in files), lipsync (sync_v2, veed_fabric_1_0, omnihuman_v1_5, ...), video editing (grok_imagine_edit), avatars (heygen_avatar), and video upscaling (topaz_video, seedvr_video).

When files contains an image and the model has an image-to-video variant, varg routes to it automatically — same model family, never substituted.

post/video

Request

  • Base URL: https://api.varg.ai/v2
  • URL: https://api.varg.ai/v2/video
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Any unique string. Retrying a request with the same key returns the existing job (HTTP 200) instead of creating and charging a new one (HTTP 202).

X-Workspace-Idstring

Folder id (uuid) or slug. The job's output is filed into this folder when the job completes. An unknown folder returns 404 workspace_not_found and no job is created. If you cannot set headers, send a top-level workspace_id field in the JSON body instead. Not part of the generation input, so it does not affect caching.

Request body

modelstring required
promptstring
aspect_ratiostring
resolution'480p' | '720p' | '1080p' | '4k'

Quality tier. Unsupported tiers fall back to the nearest available (a warning is returned).

audioboolean

Generate a native audio track (ignored by models without support)

provider_optionsProviderOptions

Provider-native overrides, keyed by provider id (e.g. a fal object with seed, num_images, ...). Discover per-model fields via GET /tools/{tool_key}?model=<model>.

Example request

{
  "model": "kling_v3",
  "aspect_ratio": "16:9"
}

Response

Idempotency replay — the existing job for this Idempotency-Key (no new charge).

idstring required
status'queued' | 'running' | 'awaiting_confirmation' | 'completed' | 'failed' | 'cancelled' required

The status only moves forward: queued → running → completed, failed or cancelled. Everything a running job goes through — sending to the provider, uploading references, switching to another provider — is a stage of running; a job never goes back to queued. (Older API builds also reported submitting; treat it as running.)

awaiting_confirmation (multi-step pipelines only): the job finished a step that asks for review and waits for POST /jobs/{id}/confirm. It is not terminal.

stage'queued' | 'submitting' | 'uploading_references' | 'rendering' | 'retrying' | 'finalizing' | 'null' nullable required

What the job is doing right now. null once the job is terminal, and while the job is awaiting_confirmation.

  • queued — waiting for a slot; no attempt yet
  • submitting — being sent to the provider
  • uploading_references — the provider is taking the reference files into its asset library (progress_message shows n/m)
  • rendering — the provider accepted the task and is generating
  • retrying — an attempt failed (the provider refused, failed or rate limited it); the job waits for its next attempt, usually on another provider. See attempts.
  • finalizing — the result is being saved and billed
toolstring required

Internal tool id (e.g. tool_2001a2b3c4d5 for video). It differs between environments and is kept for backwards compatibility. Do not compare it against GET /tools keys; use tool_key.

tool_keystring nullable required

Readable tool key (image, video, speech, pipeline, ...): the key of GET /tools, of the sugar route that created the job (POST /video → video), of GET /files?tool= and of lineage. null only if the tool registry could not be read.

inputobject required

The request body as submitted (model, prompt, ...)

errorstring nullable required

Human-readable failure message. null unless the job failed or was cancelled.

progress_messagestring nullable required
progressnumber nullable required

Fraction 0..1

progress_metadataobject nullable required
estimated_duration_msinteger nullable required
estimated_cost_centsinteger nullable required
actual_cost_centsinteger nullable required
providerstring nullable required
provider_modelstring nullable required
provider_statusstring nullable required

The provider's raw status string

provider_job_idstring nullable required
completed_by_provider_model_idstring nullable required

Provider model route that completed the job

last_attempt_provider_model_idstring nullable required

Provider model route of the most recent attempt

workspace_idstring nullable required

Folder the outputs are filed into (see X-Workspace-Id)

created_atstring date-time required
started_atstring date-time nullable required
completed_atstring date-time nullable required
warningsstring[]

Present on creation responses when the request was adjusted (for example a resolution fallback)

Example response

{
  "id": "job_a1b2c3d4e5f6",
  "attempts": [
    {
      "n": 1,
      "provider": "byteplus",
      "model_key": "byteplus:dreamina-seedance-2-5-260628",
      "reason": "real person in the reference images"
    }
  ],
  "tool": "tool_2001a2b3c4d5",
  "tool_key": "video",
  "output": {
    "outputs": [
      {
        "media_type": "video/mp4"
      }
    ]
  },
  "progress_message": "stitching 3/8 (40%)",
  "step_state": {
    "current_step": "extend"
  },
  "pricing": {
    "billed_units": {
      "images": 1
    }
  },
  "provider": "fal",
  "provider_model": "fal:flux_schnell"
}

Changes