Skip to content

Generate a video

POSThttps://api.vidmoat.com/v1/ai/videos
Bearer tokenScope ai.video40 to 320 credits per secondTry it in the playground

Start a generated clip with Grok, Alibaba HappyHorse or Wan 3.0. Returns a job to poll. Paid Studio only; trials and full-waiver promotions are excluded.

Body#

  • promptstringrequired
    Up to 800 characters; anything longer is cut to 800.
  • durationSecintegerdefault 5
    Whole seconds, from the provider's minimum (Grok 1, Wan 2, HappyHorse 3) to 15.
  • providerenumdefault grok
    qwen is Alibaba HappyHorse 1.1. Auto picks the cheapest compatible route. The default is Grok while it is configured on the deployment; otherwise, and whenever you ask for 1080p without a provider, it is auto.
    One of grok, qwen, wan, auto
  • resolutionenumdefault 720p
    Grok does not do 1080p.
    One of 480p, 720p, 1080p
  • aspectRatiostringdefault 16:9
    16:9, 9:16, 1:1, 4:3, 3:4, 4:5, 5:4, 9:21 or 21:9 (Wan: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9).
  • referenceUrlsarray of strings
    Up to 7 reference images for consistency: your uploads or public HTTPS images. Grok with references is limited to 720p. With imageUrl the shot runs on Grok Imagine 1.5 (64 credits a second); HappyHorse and Wan refuse the combination.
  • imageUrlstring
    A starting frame.
  • castIdsarray of strings
    Up to 6 saved Cast members (cm_... from GET /v1/cast). Each adds its best reference view and its description; counted with referenceUrls. Over the limit is refused with the count.
  • sceneobject
    { projectId, sceneId }: make this for a storyboard scene. The scene's cast and place are added to castIds (you can add members, never remove one), the board's style lock fills the lens and pace (a different one is refused), and for the scene's first video its continuity join or approved still is the first frame. The response lists them in scene.applied.
  • framingenum
    Which Cast views to send. Default medium.
    One of close, medium, wide
  • shotobject
    Optional shot preset, { move?, framing?, lens?, pace? }, at most one of each, added to the prompt for you. move: push_in, pull_out, orbit, pan, truck, crane_up, dolly_zoom, crash_zoom, fpv, handheld, locked_off, whip_pan; framing and lens as on images; pace: slow, normal, fast. With imageUrl or continueFrom, framing and lens are refused (the first frame fixes them). Unknown ids are refused with the list, before any charge. The response echoes shot and shotDescription.
  • continueFromobject
    { jobId | url, mode }. extend: Make it longer, the same take continues, Grok, durationSec is the 2 to 10 seconds ADDED to a 2 to 15 s source, quoted on source plus added seconds, no Cast or references. last_frame: Continue this clip, a new clip starting on the sharpest frame of the last 0.5 s (the response gives chain.trimmedSourceUrl, the source trimmed to it); works with castIds. extendFrom is accepted as an older name for the same object.
  • consistencyobject
    { check?: boolean }. With castIds, ask for the finished video to be face-checked against each member (free). The job poll does not return the verdicts: read them with POST /v1/consistency and the job id.
  • withAudiobooleandefault false
    Generate audio where the provider supports it (not HappyHorse).
  • projectIdstring
    Project to attach the job to.
  • maxCreditsnumber
    Never spend more than this.
  • quoteOnlyboolean
    true returns the route and price without starting a job.

Response#

Returns 202.

Response fields#

  • idstring
    The job id. Poll it with Get a generation job.
  • statusstring
    PROCESSING.
  • durationSecinteger
    Seconds billed.
  • shotobject
    When you sent shot: the preset applied, with shotDescription. Likewise scene, castIds, referencesUsed and, for continueFrom, chain (with trimmedSourceUrl for last_frame) when they apply.
  • creditsobject
    { charged, remaining, basis }.
  • pollstring
    The path to poll.
  • quoteOnlyboolean
    With quoteOnly: true the reply (still 202) is { route, quoteOnly: true } plus the shot, scene, Cast and chain fields, and no job is started.

Errors#

Besides the errors any request can get (authentication, rate limits):

StatusCodeWhen
400invalid_requestNo prompt; a refused reference; or a provider, resolution, duration, aspect ratio or continueFrom the chosen model cannot do (the message says which).
404not_foundprojectId is not one of your projects.
402plan_requiredThe plan has no video generation.
402insufficient_creditsNot enough credits, or the account is on a trial or a full-waiver promotion.
402quota_exceededA video job is already running on the account.
422prompt_rejectedThe prompt failed the safety check. Nothing was charged. field names the field.
502provider_errorThe generation provider failed. The charge is refunded.