# Cancel a movie Source: https://docs.keyframe.art/api-reference/movies/cancel-a-movie /openapi/keyframe.v1.yaml post /movies/{movie_id}/cancel Cancel a movie job if it has not completed. # Create a movie Source: https://docs.keyframe.art/api-reference/movies/create-a-movie /openapi/keyframe.v1.yaml post /movies Create an asynchronous movie generation job. # Estimate a movie Source: https://docs.keyframe.art/api-reference/movies/estimate-a-movie /openapi/keyframe.v1.yaml post /movies/estimate Estimate credits and rough runtime before creating a billable movie job. # Get a movie Source: https://docs.keyframe.art/api-reference/movies/get-a-movie /openapi/keyframe.v1.yaml get /movies/{movie_id} Retrieve a movie job and its current status. # List movie assets Source: https://docs.keyframe.art/api-reference/movies/list-movie-assets /openapi/keyframe.v1.yaml get /movies/{movie_id}/assets List generated assets for a movie, including the final export when ready. # Upload a reference Source: https://docs.keyframe.art/api-reference/references/upload-a-reference /openapi/keyframe.v1.yaml post /references Upload an image, video, audio file, or document to use as generation context. # Authentication Source: https://docs.keyframe.art/authentication Authenticate requests with a Keyframe API key. # Authentication The API uses bearer keys. ```bash theme={null} Authorization: Bearer $KEYFRAME_API_KEY ``` Keep keys server-side. Do not ship them in browsers, mobile apps, public repos, or client config. ## Idempotency Send an `Idempotency-Key` header when creating movies or other billable jobs. ```bash theme={null} Idempotency-Key: launch-film-001 ``` If the same key is retried with the same body, Keyframe returns the original job. This prevents accidental duplicate spend. ## Environments The planned production base URL is: ```txt theme={null} https://api.keyframe.art/v1 ``` Sandbox and preview environments may be added during beta. # Movie jobs Source: https://docs.keyframe.art/concepts/movie-jobs How Keyframe creates and tracks generated movies. # Movie jobs A movie is an async job. Creating one starts a pipeline: planning, reference analysis, image generation, video generation, audio, review, stitching, and export. ## Status values | Status | Meaning | | ------------ | ------------------------------------------------------------------------- | | `queued` | The request has been accepted and is waiting to start. | | `planning` | Keyframe is turning the prompt and references into a production plan. | | `generating` | Keyframe is generating storyboards, clips, audio, or intermediate assets. | | `rendering` | Keyframe is assembling the final export. | | `completed` | The final movie is ready. | | `failed` | The job failed and includes an error object. | | `canceled` | The job was canceled before completion. | ## Duration and aspect ratio v1 starts with simple constraints: * `duration_seconds`: target story duration. * `aspect_ratio`: `16:9`, `9:16`, `1:1`, or `4:5`. * `style`: natural-language creative direction. Keyframe may round internal clip lengths to match model constraints. The final timeline still targets the requested story duration. ## Outputs Completed jobs can expose multiple assets: * final video export * generated storyboard frames * individual video clips * audio tracks * review or planning metadata Use the assets endpoint to list available outputs for a movie. # References Source: https://docs.keyframe.art/concepts/references Use images, videos, audio, and documents to guide movie generation. # References References are durable inputs. Upload once, then attach by ID. ## Reference roles | Role | Use | | ----------- | -------------------------------------------------------------- | | `character` | Preserve a person, mascot, or fictional character. | | `product` | Preserve the appearance of a product or object. | | `location` | Preserve a room, set, venue, or environment. | | `style` | Guide art direction, color, lensing, or motion style. | | `audio` | Provide music, voice, ambience, or sound-design direction. | | `document` | Provide scripts, briefs, brand guidelines, or product details. | | `other` | Attach additional context that does not fit another role. | ## Upload guidance Use clean source media. For products and characters, avoid crops, compression, filters, and text overlays. ## Prompting with references Movie prompts describe the outcome. Reference descriptions explain how each file should be used. ```json theme={null} { "reference_id": "ref_abc123", "role": "location", "description": "Use this studio as the main interior location. Preserve the concrete floor and curved back wall." } ``` # Errors Source: https://docs.keyframe.art/errors Understand API error responses and retry behavior. # Errors Errors use one shape. ```json theme={null} { "error": { "code": "invalid_request", "message": "duration_seconds must be between 5 and 120.", "request_id": "req_abc123" } } ``` ## Common codes | Code | Meaning | | ----------------------- | ----------------------------------------------------------- | | `invalid_request` | The request body, parameters, or uploaded file are invalid. | | `authentication_failed` | The API key is missing, invalid, or expired. | | `permission_denied` | The key does not have access to the requested resource. | | `not_found` | The requested resource does not exist. | | `rate_limited` | The request exceeded the current rate limit. | | `provider_unavailable` | A generation provider is temporarily unavailable. | | `internal_error` | An unexpected error occurred. | ## Retrying requests Retry transient `429`, `502`, `503`, and `504` responses with exponential backoff. For billable creation endpoints, always include an `Idempotency-Key` header before retrying. # Introduction Source: https://docs.keyframe.art/introduction Build movies from prompts, references, and production constraints. # Keyframe API The Keyframe API turns a brief and a few references into a movie. It has four primitives: * **References** are uploaded images, videos, audio files, or documents that guide generation. * **Movies** are async jobs that plan, generate, review, and render a video. * **Assets** are the outputs created during a movie job, including storyboards, clips, audio, and final exports. * **Webhooks** report progress and completion. The API is intentionally high level. You give Keyframe intent and constraints. Keyframe owns the graph, model routing, retries, review, and export. ```txt theme={null} Upload references -> Create a movie job -> Poll or receive webhooks -> Download assets ``` ## API status The API is in beta. Endpoint paths, schemas, limits, and pricing may change before v1 launch. ## Base URL ```txt theme={null} https://api.keyframe.art/v1 ``` Use the `docs.keyframe.art` site for documentation and API reference. Use `api.keyframe.art` for runtime API calls. # Quickstart Source: https://docs.keyframe.art/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. # Webhooks Source: https://docs.keyframe.art/webhooks Receive movie job lifecycle events. # Webhooks Use webhooks instead of polling. Pass `webhook_url` when creating a movie. Keyframe sends lifecycle events as the job progresses. ```json theme={null} { "type": "movie.completed", "movie_id": "movie_abc123", "created_at": "2026-06-25T20:15:00Z", "data": { "status": "completed" } } ``` ## Event types | Event | Description | | ---------------------- | --------------------------------- | | `movie.status_changed` | The movie changed status. | | `movie.completed` | The movie completed successfully. | | `movie.failed` | The movie failed. | | `movie.canceled` | The movie was canceled. | ## Delivery expectations Delivery is at least once. Store processed event IDs and make handlers idempotent. Return `2xx` to acknowledge receipt. Non-`2xx` responses may be retried with backoff. Webhook signing details will be documented before public availability.