Skip to main content

​
Quickstart

​
1. Upload a reference

Upload reference media first. The response includes a durable reference_id. 
curl https://api.keyframe.art/v1/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 https://api.keyframe.art/v1/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 https://api.keyframe.art/v1/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 https://api.keyframe.art/v1/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 https://api.keyframe.art/v1/movies/movie_abc123/assets \
  -H "Authorization: Bearer $KEYFRAME_API_KEY"
Asset URLs are temporary. Store asset IDs, not signed URLs.