Quickstart

These examples describe the proposed v1 API and cannot run against a live endpoint yet. KEYFRAME_API_BASE_URL represents the future v1 base URL; no production value is currently available.

1. Upload a reference

Upload reference media first. The response includes a durable reference_id.

curl "${KEYFRAME_API_BASE_URL:?Public v1 API is not deployed}/references" \
  -H "Authorization: Bearer $KEYFRAME_API_KEY" \
  -F "[email protected]" \
  -F "role=product" \
  -F "description=The hero product should appear exactly like this."

2. Estimate the job

Estimate credits before creating a billable job.

curl "${KEYFRAME_API_BASE_URL:?Public v1 API is not deployed}/movies/estimate" \
  -H "Authorization: Bearer $KEYFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a cinematic 30 second launch film for a compact desk lamp.",
    "duration_seconds": 30,
    "aspect_ratio": "16:9",
    "references": [
      {
        "reference_id": "ref_abc123",
        "role": "product"
      }
    ]
  }'

3. Create a movie

Create a movie job with a prompt and the references that should guide it.

curl "${KEYFRAME_API_BASE_URL:?Public v1 API is not deployed}/movies" \
  -H "Authorization: Bearer $KEYFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-film-001" \
  -d '{
    "prompt": "Create a cinematic 30 second launch film for a compact desk lamp.",
    "duration_seconds": 30,
    "aspect_ratio": "16:9",
    "style": "cinematic product film",
    "references": [
      {
        "reference_id": "ref_abc123",
        "role": "product"
      }
    ],
    "webhook_url": "https://example.com/webhooks/keyframe"
  }'

4. Check job status

Movie generation is async. Poll until status is completed, or use webhooks.

curl "${KEYFRAME_API_BASE_URL:?Public v1 API is not deployed}/movies/movie_abc123" \
  -H "Authorization: Bearer $KEYFRAME_API_KEY"

5. Download the final export

When the movie is complete, list its assets and download the final export.

curl "${KEYFRAME_API_BASE_URL:?Public v1 API is not deployed}/movies/movie_abc123/assets" \
  -H "Authorization: Bearer $KEYFRAME_API_KEY"

Asset URLs are temporary. Store asset IDs, not signed URLs.

Get started

Core concepts

API reference

Quickstart

Quickstart

1. Upload a reference

2. Estimate the job

3. Create a movie

4. Check job status

5. Download the final export

​Quickstart

​1. Upload a reference

​2. Estimate the job

​3. Create a movie

​4. Check job status

​5. Download the final export

Quickstart

1. Upload a reference

2. Estimate the job

3. Create a movie

4. Check job status

5. Download the final export