--- title: "POST /api/boreal/" method: POST path: "/api/boreal/" tags: ["boreal"] --- # POST /api/boreal/ `POST /api/boreal/` ## Request - The document declares no server URL. - Auth: API key in header `X-API-ID` and API key in header `X-API-KEY` Generate a video from a prompt with Boreal (optional start image and audio track) or Boreal-H3 (``model: "boreal-h3"``: optional start and closing frames, or reference images, videos and audio). Async only: POST returns the job immediately; poll the detail route or supply ``webhook_url``. ## Request body - APIBoreal - `id` string, uuid, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `model` 'boreal' | 'boreal-h3': * `boreal` - Boreal * `boreal-h3` - Boreal H3 - `prompt` string, required: Describe the video: subject, action, camera, and any dialogue or sound it should contain. In a boreal-h3 reference render, refer to the references by type and order: Image 1, Image 2, Video 1, Audio 1. - `image_url` string, uri, nullable: Optional start frame. boreal follows the image's own aspect ratio unless aspect_ratio names one, which centre-crops the image to it; boreal-h3 always follows the image's ratio. - `end_image_url` string, uri, nullable: boreal-h3 only: optional closing frame. Requires image_url. - `audio_url` string, uri, nullable: boreal only: optional audio track ('mp3' or 'wav') that drives the video. When set, the video is as long as the audio, within the same per-resolution limit, and duration is ignored. - `reference_image_urls` string[]: boreal-h3 only: up to 9 reference images for reference-to-video. A reference render needs at least one image or video reference and takes no image_url. The first 5 are free; each one after that costs 0.2 credits. - `reference_video_urls` string[]: boreal-h3 only: up to 3 reference videos for reference-to-video, billed on top of the output per second of their combined length (counted up to 15 seconds): 0.4 credits at 768p, 0.6 at 1088p and 2k. The whole boreal-h3 price is rounded up to half a credit. - `reference_audio_urls` string[]: boreal-h3 only: up to 3 reference audio tracks, alongside at least one image or video reference. - `resolution` '720p' | '1080p' | '2k' | '768p' | '1088p': * `720p` - 720p * `1080p` - 1080p * `2k` - 2k * `768p` - 768p * `1088p` - 1088p - `aspect_ratio` 'auto' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4': * `auto` - auto * `16:9` - 16:9 * `9:16` - 9:16 * `1:1` - 1:1 * `4:3` - 4:3 * `3:4` - 3:4 - `duration` number, double: Video length in seconds. boreal: greater than 0 and at most 60 at 720p, 30 at 1080p and 15 at 2k. boreal-h3: a whole number from 5 to 15. - `negative_prompt` string, nullable: boreal only: what the video should avoid. - `prompt_enhancement` 'auto' | 'none': * `auto` - auto * `none` - none - `ttl_days` integer, nullable: Optional. Days the generated video is retained before automatic deletion (1-7); actual deletion lands within `[ttl_days, ttl_days + 2]` days of creation. Omit to keep the video with no expiry (zero-data-retention accounts default to 1). - `expires_at` string, nullable, required: ISO-8601 timestamp at which the generated video becomes eligible for deletion, or null when it does not expire. Actual deletion can lag up to 48h after this. - `output_upload_url` string, uri: Optional. An https presigned PUT URL you own (for example S3 or GCS). When set, the finished mp4 is uploaded there with `Content-Type: video/mp4` and deleted from Creatify's storage, so `video_output` stays null. If the upload fails, the job fails and is refunded. Never echoed back in responses. - `webhook_url` string, uri, nullable - `status` 'pending' | 'in_queue' | 'running' | 'failed' | 'done' | 'rejected', required: * `pending` - Pending * `in_queue` - In Queue * `running` - Running * `failed` - Failed * `done` - Done * `rejected` - Rejected - `failed_reason` string, required: Failed reason - `video_output` string, nullable, required: Video output URL - `credits_used` number, required: Credits used in this API call - `progress` number, double, required: Progress of the job ## Response `201` - APIBoreal - `id` string, uuid, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `model` 'boreal' | 'boreal-h3': * `boreal` - Boreal * `boreal-h3` - Boreal H3 - `prompt` string, required: Describe the video: subject, action, camera, and any dialogue or sound it should contain. In a boreal-h3 reference render, refer to the references by type and order: Image 1, Image 2, Video 1, Audio 1. - `image_url` string, uri, nullable: Optional start frame. boreal follows the image's own aspect ratio unless aspect_ratio names one, which centre-crops the image to it; boreal-h3 always follows the image's ratio. - `end_image_url` string, uri, nullable: boreal-h3 only: optional closing frame. Requires image_url. - `audio_url` string, uri, nullable: boreal only: optional audio track ('mp3' or 'wav') that drives the video. When set, the video is as long as the audio, within the same per-resolution limit, and duration is ignored. - `reference_image_urls` string[]: boreal-h3 only: up to 9 reference images for reference-to-video. A reference render needs at least one image or video reference and takes no image_url. The first 5 are free; each one after that costs 0.2 credits. - `reference_video_urls` string[]: boreal-h3 only: up to 3 reference videos for reference-to-video, billed on top of the output per second of their combined length (counted up to 15 seconds): 0.4 credits at 768p, 0.6 at 1088p and 2k. The whole boreal-h3 price is rounded up to half a credit. - `reference_audio_urls` string[]: boreal-h3 only: up to 3 reference audio tracks, alongside at least one image or video reference. - `resolution` '720p' | '1080p' | '2k' | '768p' | '1088p': * `720p` - 720p * `1080p` - 1080p * `2k` - 2k * `768p` - 768p * `1088p` - 1088p - `aspect_ratio` 'auto' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4': * `auto` - auto * `16:9` - 16:9 * `9:16` - 9:16 * `1:1` - 1:1 * `4:3` - 4:3 * `3:4` - 3:4 - `duration` number, double: Video length in seconds. boreal: greater than 0 and at most 60 at 720p, 30 at 1080p and 15 at 2k. boreal-h3: a whole number from 5 to 15. - `negative_prompt` string, nullable: boreal only: what the video should avoid. - `prompt_enhancement` 'auto' | 'none': * `auto` - auto * `none` - none - `ttl_days` integer, nullable: Optional. Days the generated video is retained before automatic deletion (1-7); actual deletion lands within `[ttl_days, ttl_days + 2]` days of creation. Omit to keep the video with no expiry (zero-data-retention accounts default to 1). - `expires_at` string, nullable, required: ISO-8601 timestamp at which the generated video becomes eligible for deletion, or null when it does not expire. Actual deletion can lag up to 48h after this. - `output_upload_url` string, uri: Optional. An https presigned PUT URL you own (for example S3 or GCS). When set, the finished mp4 is uploaded there with `Content-Type: video/mp4` and deleted from Creatify's storage, so `video_output` stays null. If the upload fails, the job fails and is refunded. Never echoed back in responses. - `webhook_url` string, uri, nullable - `status` 'pending' | 'in_queue' | 'running' | 'failed' | 'done' | 'rejected', required: * `pending` - Pending * `in_queue` - In Queue * `running` - Running * `failed` - Failed * `done` - Done * `rejected` - Rejected - `failed_reason` string, required: Failed reason - `video_output` string, nullable, required: Video output URL - `credits_used` number, required: Credits used in this API call - `progress` number, double, required: Progress of the job ## Changes - **2026-11-03** `8423ba73b422`: 1 info - endpoint added [Operation history](https://skmtc.dev/creatify/apis/creatify-ai-api/changes/api/boreal/post.md) --- [API](https://skmtc.dev/creatify/apis/creatify-ai-api.md) - [All operations](https://skmtc.dev/creatify/apis/creatify-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/creatify/apis/creatify-ai-api/revisions/8423ba73b422?raw)