Skip to navigation

Model 1

Submit a generation, poll its status, and download the MP4.

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.

set -euo pipefail
export VIDEOGEN_API_KEY="sk_videogen_live_..."
IDEMPOTENCY_KEY="$(uuidgen)"
GENERATION_ID=$(curl --fail-with-body --silent --show-error \
https://api.videogen.io/v1/models/model-1/generations \
-H "Authorization: Bearer $VIDEOGEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{"prompt":"A cinematic close-up of a sparkling water can on ice.","seconds":10}' \
| jq -er '.generationId')
while true; do
GENERATION=$(curl --fail-with-body --silent --show-error \
"https://api.videogen.io/v1/models/model-1/generations/$GENERATION_ID" \
-H "Authorization: Bearer $VIDEOGEN_API_KEY") || exit 1
STATUS=$(printf '%s' "$GENERATION" | jq -r '.status')
case "$STATUS" in
succeeded)
DOWNLOAD_URL=$(printf '%s' "$GENERATION" | jq -er '.result.downloadUrl') || exit 1
curl --fail --location "$DOWNLOAD_URL" --output model-1.mp4 || exit 1
break
;;
failed)
printf '%s\n' "$GENERATION" | jq '.error' >&2
exit 1
;;
queued|running) sleep 10 ;;
*) printf 'Unexpected generation status: %s\n' "$STATUS" >&2; exit 1 ;;
esac
done

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.

HTTPcodeWhat to do
400invalid_parametersCorrect the field or header identified in message.
403model_1_access_requiredRequest Model 1 access or an increased allowance for this team. Buying credits does not enable access.
429model_1_hourly_quota_exceededWait the positive number of seconds in Retry-After, then retry the identical request with the same key. The message includes the current allowance and estimated wait when available.
429model_1_total_quota_exceededReduce duration or request a higher lifetime allowance. The message includes requested and remaining seconds when available. No timed Retry-After is supplied. Waiting or buying credits does not replenish this allowance.
409idempotency_conflictReuse the original request, or choose a new key for a new generation. A key used by another user on your team cannot be reused.
503model_1_unavailableNew generation is temporarily paused. Try later; existing generations remain readable.

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.