> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Model 1

Model 1 uses a separate team quota shared with the Model 1 app. Request access at [Model 1](https://app.videogen.io/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.

```bash
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](/file-uploads), 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.

| HTTP | `code`                          | What to do                                                                                                                                                                                                                    |
| ---- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `invalid_parameters`            | Correct the field or header identified in `message`.                                                                                                                                                                          |
| 403  | `model_1_access_required`       | Request Model 1 access or an increased allowance for this team. Buying credits does not enable access.                                                                                                                        |
| 429  | `model_1_hourly_quota_exceeded` | Wait 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.                                       |
| 429  | `model_1_total_quota_exceeded`  | Reduce 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. |
| 409  | `idempotency_conflict`          | Reuse the original request, or choose a new key for a new generation. A key used by another user on your team cannot be reused.                                                                                               |
| 503  | `model_1_unavailable`           | New 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.