Generate a video
POST
https://api.vidmoat.com/v1/ai/videosStart 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#
promptstringrequiredUp to 800 characters; anything longer is cut to 800.durationSecintegerdefault5Whole seconds, from the provider's minimum (Grok 1, Wan 2, HappyHorse 3) to 15.providerenumdefaultgrokqwenis 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 isauto.One ofgrok,qwen,wan,autoresolutionenumdefault720pGrok does not do 1080p.One of480p,720p,1080paspectRatiostringdefault16:916: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 stringsUp to 7 reference images for consistency: your uploads or public HTTPS images. Grok with references is limited to 720p. WithimageUrlthe shot runs on Grok Imagine 1.5 (64 credits a second); HappyHorse and Wan refuse the combination.imageUrlstringA starting frame.castIdsarray of stringsUp to 6 saved Cast members (cm_...from GET /v1/cast). Each adds its best reference view and its description; counted withreferenceUrls. 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 tocastIds(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 inscene.applied.framingenumWhich Cast views to send. Default medium.One ofclose,medium,wideshotobjectOptional 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. WithimageUrlorcontinueFrom, framing and lens are refused (the first frame fixes them). Unknown ids are refused with the list, before any charge. The response echoesshotandshotDescription.continueFromobject{ jobId | url, mode }.extend: Make it longer, the same take continues, Grok,durationSecis 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 giveschain.trimmedSourceUrl, the source trimmed to it); works withcastIds.extendFromis accepted as an older name for the same object.consistencyobject{ check?: boolean }. WithcastIds, 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.withAudiobooleandefaultfalseGenerate audio where the provider supports it (not HappyHorse).projectIdstringProject to attach the job to.maxCreditsnumberNever spend more than this.quoteOnlybooleantruereturns the route and price without starting a job.
Response#
Returns 202.
Response fields#
idstringThe job id. Poll it with Get a generation job.statusstringPROCESSING.durationSecintegerSeconds billed.shotobjectWhen you sentshot: the preset applied, withshotDescription. Likewisescene,castIds,referencesUsedand, forcontinueFrom,chain(withtrimmedSourceUrlforlast_frame) when they apply.creditsobject{ charged, remaining, basis }.pollstringThe path to poll.quoteOnlybooleanWithquoteOnly: truethe reply (still202) 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):
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | No prompt; a refused reference; or a provider, resolution, duration, aspect ratio or continueFrom the chosen model cannot do (the message says which). |
| 404 | not_found | projectId is not one of your projects. |
| 402 | plan_required | The plan has no video generation. |
| 402 | insufficient_credits | Not enough credits, or the account is on a trial or a full-waiver promotion. |
| 402 | quota_exceeded | A video job is already running on the account. |
| 422 | prompt_rejected | The prompt failed the safety check. Nothing was charged. field names the field. |
| 502 | provider_error | The generation provider failed. The charge is refunded. |