> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keyframe.art/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a movie job from a prompt and references.

# Quickstart

## 1. Upload a reference

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

```bash theme={null}
curl https://api.keyframe.art/v1/references \
  -H "Authorization: Bearer $KEYFRAME_API_KEY" \
  -F "file=@product-photo.png" \
  -F "role=product" \
  -F "description=The hero product should appear exactly like this."
```

## 2. Estimate the job

Estimate credits before creating a billable job.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.