Model 1
Model 1 uses a separate team quota shared with the Model 1 app. Request access at Model 1 before generating. API generation credits and top-ups do not increase this quota.
Submit, poll, download
Use your existing API key or supported OAuth Bearer token. Generate one Idempotency-Key per intended video. If submission times out, retry the same request with the same key. Changed inputs require a new key. An identical retry returns the same generation without reserving quota twice.
Submission returns 202 with generationId and a Location header for polling. queued and running are nonterminal. Generations take minutes, so poll every 5–10 seconds. Stop polling on succeeded or failed. An HTTP disconnect does not cancel the generation. There is no separate export step, cancellation endpoint, or webhook for Model 1. A completed result contains fileId, downloadUrl, and downloadUrlExpiresAt (Unix seconds). If you archive the output file, the generation stays succeeded and result becomes null. Download directly from that signed URL without sending your API credentials to file storage. Read the generation again to refresh an expiring URL. A quality warning can accompany a successful result.
Inputs
prompt is required, nonblank, and limited to 20,000 characters. seconds defaults to 10 and accepts integers from 4 through 600. The Idempotency-Key header must contain 16–100 characters. Unknown JSON fields are rejected. Resolution, aspect ratio, audio, and other output settings follow current Model 1 defaults; the endpoint exposes no seed, resolution, or quality controls.
Optional imageFileIds accepts an ordered array of up to 9 distinct, accessible, fully uploaded images. More than 9 IDs or a repeated ID returns 400 invalid_parameters. Reference images are resized automatically; the original file size does not impose a separate Model 1 limit. Use the existing file upload flow, then pass the resulting vg_file_... IDs. Images guide generation as references; they do not guarantee the opening frame. Omitting imageFileIds is equivalent to an empty array. Omitting seconds is equivalent to 10 when checking idempotent retries.
Quota and errors
GET /v1/models/model-1/quota reports callsPerHour, callsRemaining, nextCallAt, totalSeconds, usedSeconds, reservedSeconds, and remainingSeconds. nextCallAt is Unix seconds or null. Remaining seconds exclude reservations. A missing quota returns zero balances. Snapshots are advisory: concurrent starts and app usage can consume availability before your next submission.
Each admitted attempt holds a rolling-hour call slot and reserves its requested duration. Success transfers reserved seconds into used seconds. Failed attempts retain their call slot and reserved duration for operator recovery. Invalid and quota-rejected submissions reserve nothing. This allowance does not reset daily or monthly.
Authentication and resource errors use the existing 401, 403 not_authorized (or permission_denied for files), and 404 not_found conventions. A generation ID that belongs to another team returns the same 404 not_found as an unknown ID. Malformed encoded IDs can return the existing 400 invalid_id code. Unexpected service errors remain 5xx. Generation failures appear in the polled response’s error with content_policy_violation or generation_failed. Branch on code, not the exact message text.
SDKs and CLI
TypeScript: client.models.startModel1Generation({prompt, seconds: 10}, {idempotencyKey}), client.models.getModel1Generation({generationId}), and client.models.getModel1Quota(). HTTP failures preserve status/body and expose VideoGenError.retryAfter as the original header string or null.
Python sync/async clients expose client.models.start_model1_generation(prompt=prompt, seconds=10, idempotency_key=key), get_model1_generation(generation_id=id), and get_model1_quota(). HTTP failures expose VideoGenError.retry_after.
CLI: videogen models start-model1-generation --idempotency-key YOUR_UNIQUE_KEY --body '{"prompt":"A cinematic product reveal","seconds":10}', videogen models get-model1-generation --generation-id GENERATION_ID, and videogen models get-model1-quota. CLI errors include retryAfter when returned by the API. Poll explicitly; these commands do not add a --wait mode.