AI Video Generation API

Available models

Call /api/v1/ai-video-generation/models for the current machine-readable limits. Only public model IDs and capabilities are returned.

Text-only generation

Send the prompt and model settings directly to POST /jobs. Idempotency-Key is required: repeating the same request returns the original job, while changing the body for that key returns 409. The only cross-body exception is the signed-upload transition described below: start that same draft with its original key and a body containing its generationId.

curl -X POST https://www.subclip.app/api/v1/ai-video-generation/jobs \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-request-001" \
  -d '{
  "modelId": "kling-v3",
  "prompt": "A cinematic tracking shot of a sailboat crossing calm water at sunrise",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "durationSeconds": 5,
  "generateAudio": false
}'

Multimodal generation

If the reference is already hosted, include its direct public HTTPS download URL in POST /jobs. Subclip rejects private-network hosts. Downloading and media verification continue asynchronously after acceptance, so an unreachable URL, invalid file, or mismatched media type can later produce status: failed with error.code: INPUT_INVALID.

curl -X POST https://www.subclip.app/api/v1/ai-video-generation/jobs \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-request-url-001" \
  -d '{
  "modelId": "ltx-2-3-pro",
  "prompt": "Continue @video_1 with a slow cinematic push toward the subject",
  "aspectRatio": "16:9",
  "resolution": "1080p",
  "durationSeconds": 6,
  "generateAudio": false,
  "assets": [
    {
      "kind": "video",
      "role": "source_video",
      "url": "https://cdn.yoursite.com/reference.mp4"
    }
  ]
}'

For a local file, use the signed-upload flow:

1. Create an awaiting_upload draft with the prompt, model settings, and asset metadata through POST /uploads. Its response includes the 15-minute uploadExpiresAt deadline and uploadExpiresIn.
2. PUT every file to its returned URL using the declared content type and exact content length. Wait for every PUT response and require a successful status.
3. Start the saved draft with POST /jobs, a body containing only the returned generationId, and the same Idempotency-Key used for POST /uploads. This upload-to-start step is the intentional exception to the usual same-key/same-body rule.

No client-side delay is required after every PUT completes successfully. Subclip verifies each upload and copies it to immutable job input storage before dispatch. If this step returns upload_missing (400), upload_verification_failed (502), or upload_lock_failed (502), treat Retry-After as the minimum delay and retry POST /jobs with the same generationId, identical body, and same Idempotency-Key. Use exponential backoff with jitter (for example 1, 2, 4, and 8 seconds, capped at 15 seconds) and stop at uploadExpiresAt. Do not create a second draft unless the API returns 410 upload_expired.

curl -X POST https://www.subclip.app/api/v1/ai-video-generation/uploads \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-request-002" \
  -d '{
  "modelId": "kling-v3",
  "prompt": "Use the reference as the opening frame, then move the camera forward slowly",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "durationSeconds": 5,
  "generateAudio": false,
  "assets": [
    {
      "id": "reference-1",
      "kind": "image",
      "fileName": "reference.jpg",
      "contentType": "image/jpeg",
      "fileSize": 2483921
    }
  ]
}'

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 2483921" \
  --upload-file ./reference.jpg

curl -X POST https://www.subclip.app/api/v1/ai-video-generation/jobs \
  -H "Authorization: Bearer $SUBCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-request-002" \
  -d '{
  "generationId": "aiapi_..."
}'

Status, download, cancel, and automatic retention

POST /uploads creates an awaiting_upload draft, not a running generation. After POST /jobs returns 200 or 202, keep polling that same generationId every five seconds while it is queued or processing. Do not submit a replacement or change its model while it is active.

Treat status as authoritative. The public vocabulary is awaiting_upload for a draft; queued and processing for a started, non-terminal job; and completed, failed, or canceled for outcomes. Completed and failed are terminal; canceled is terminal when cancellationPending is false. That flag can be true only after an explicit cancel request. When it is true, keep polling that same canceled job until it becomes false.

Download only after status: completed and outputReady: true. Save every item in downloads before the earlier of its signed-URL expiresAt and the job's resultExpiresAt. Use cancel only for an explicit user cancellation. A processing job can temporarily return status: canceled, cancellationPending: true, and resultExpiresAt: null; its one-hour access window starts when cancellation finishes.

Starting or replaying a draft after uploadExpiresAt returns 410 upload_expired. Status, download, or cancel requests for a terminal result past resultExpiresAt return 410 generation_expired. After the central sweep removes either record, its generationId returns 404 generation_not_found.

curl https://www.subclip.app/api/v1/ai-video-generation/jobs/aiapi_... \
  -H "Authorization: Bearer $SUBCLIP_API_KEY"

DOWNLOAD_JSON=$(curl -s https://www.subclip.app/api/v1/ai-video-generation/jobs/aiapi_.../download \
  -H "Authorization: Bearer $SUBCLIP_API_KEY")

echo "$DOWNLOAD_JSON" | jq -r '.downloads[] | [.downloadUrl, .fileName] | @tsv' | \
while IFS=$'\t' read -r DOWNLOAD_URL FILE_NAME; do
  curl -L "$DOWNLOAD_URL" -o "$FILE_NAME"
done

curl -X POST https://www.subclip.app/api/v1/ai-video-generation/jobs/aiapi_.../cancel \
  -H "Authorization: Bearer $SUBCLIP_API_KEY"

Credits and errors