---
title: "Plan a creative video"
canonical_url: https://docs.zvid.io/docs/endpoints/plan-creative-video/
source: docs/endpoints/plan-creative-video.api.mdx
content_revision: 6338386a1dd87e4a
---

# Plan a creative video

`POST /api/render/creative-plan/api-key`

Build a free, plan-aware art-direction plan before authoring project JSON.
The response includes scene roles and timing, style/layout directions,
creative-library and stock-media queries, variation seeds, recent-asset
exclusions, and the fallback workflow used when no complete template fits.

This endpoint does not enqueue a render or consume credits.


## Authentication

`x-api-key: YOUR_API_KEY` (header). API key for authentication. Create one in your dashboard.

Create API keys at [app.zvid.io/api-keys](https://app.zvid.io/api-keys). Keep credentials on your server.

## Parameters

This operation has no path, query, or additional header parameters.

## Request

The shell examples read credentials from `ZVID_API_KEY` (or `ZVID_ACCESS_TOKEN` for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

A request body is required.


### application/json

Unknown properties are rejected. Required properties: `brief`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `body.brief` | string | Yes | What the video should communicate, for whom, and the desired outcome. Minimum length: `3`. Maximum length: `4000`. |
| `body.variationMode` | `"consistent"` / `"fresh"` / `"explore"` | No | Stable repeatable output, one new direction, or 2-5 materially different directions. Default: `"fresh"`. |
| `body.variationSeed` | string OR integer | No | Optional reproducible creative seed. Exactly one of the listed alternatives must match. |
| `body.exploreCount` | integer | No | Default: `3`. Minimum: `2`. Maximum: `5`. |
| `body.aspectRatio` | `"16:9"` / `"9:16"` / `"1:1"` / `"4:5"` / `"custom"` | No | Default: `"16:9"`. |
| `body.duration` | number | No | Desired final duration. The response caps it to the caller's plan. Default: `15`. Minimum: `0.1`. Maximum: `86400`. |
| `body.style` | string | No | Built-in style-pack id or auto. Default: `"auto"`. Maximum length: `100`. |
| `body.motionIntensity` | `"restrained"` / `"balanced"` / `"energetic"` | No |  |
| `body.preferredMedia` | `"image"` / `"video"` / `"mixed"` | No | Default: `"mixed"`. |
| `body.recentAssetSlugs` | array of string | No | Recently used creative-library slugs to exclude from fresh or explore work. Maximum items: `20`. |
| `body.brand` | [CreativeBrandKit](#schema-creative-brand-kit) | No |  |

**Nested field: `body.variationSeed`**

Optional reproducible creative seed.

Exactly one of the listed alternatives must match.

**oneOf alternative 1**

Minimum length: `1`. Maximum length: `128`.

Type: string.

**oneOf alternative 2**

Type: integer.

**Nested field: `body.recentAssetSlugs`**

Recently used creative-library slugs to exclude from fresh or explore work.

Maximum items: `20`.

**Array item: `body.recentAssetSlugs[]`**

Maximum length: `255`.

Type: string.


### Request example: Example


```bash
curl --request POST 'https://api.zvid.io/api/render/creative-plan/api-key' \
  --header "x-api-key: $ZVID_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "brief": "Launch an AI analytics product for SaaS teams",
  "variationMode": "explore",
  "exploreCount": 3,
  "aspectRatio": "9:16",
  "duration": 20,
  "style": "modern-saas",
  "recentAssetSlugs": [
    "saas-launch-one",
    "gradient-hero"
  ],
  "brand": {
    "name": "Acme",
    "primaryColor": "#6633FF",
    "headlineFont": "Sora"
  }
}'
```

## Responses


### HTTP 200

Creative plan generated

Content type: `application/json`.

Required properties: `creativePlanVersion`, `request`, `variation`, `directions`, `creativeWorkflow`, `nextActions`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.creativePlanVersion` | string | Yes |  |
| `response.schemaVersion` | string | No |  |
| `response.sourceOfTruth` | string | No |  |
| `response.planLimits` | object | No |  |
| `response.request` | object | Yes |  |
| `response.variation` | object | Yes |  |
| `response.searchQueries` | object | No |  |
| `response.exclusions` | array of string | No |  |
| `response.directions` | array of object | Yes | One direction for consistent/fresh or 2-5 materially different directions for explore. |
| `response.creativeWorkflow` | object | Yes | Template selection, no-exact-match fallback, anti-repetition, build-order and quality-gate rules. |
| `response.nextActions` | array of string | Yes |  |
| `response.warnings` | array of string | No |  |

**Nested field: `response.exclusions`**

**Array item: `response.exclusions[]`**

Type: string.

**Nested field: `response.directions`**

One direction for consistent/fresh or 2-5 materially different directions for explore.

**Array item: `response.directions[]`**

Type: object.

**Nested field: `response.nextActions`**

**Array item: `response.nextActions[]`**

Type: string.

**Nested field: `response.warnings`**

**Array item: `response.warnings[]`**

Type: string.


### HTTP 400

Invalid creative brief or options

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 401

Unauthorized

Content type: `application/json`.

Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 500

Internal server error

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


## Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.


### schema creative plan request

**CreativePlanRequest**


Unknown properties are rejected. Required properties: `brief`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `CreativePlanRequest.brief` | string | Yes | What the video should communicate, for whom, and the desired outcome. Minimum length: `3`. Maximum length: `4000`. |
| `CreativePlanRequest.variationMode` | `"consistent"` / `"fresh"` / `"explore"` | No | Stable repeatable output, one new direction, or 2-5 materially different directions. Default: `"fresh"`. |
| `CreativePlanRequest.variationSeed` | string OR integer | No | Optional reproducible creative seed. Exactly one of the listed alternatives must match. |
| `CreativePlanRequest.exploreCount` | integer | No | Default: `3`. Minimum: `2`. Maximum: `5`. |
| `CreativePlanRequest.aspectRatio` | `"16:9"` / `"9:16"` / `"1:1"` / `"4:5"` / `"custom"` | No | Default: `"16:9"`. |
| `CreativePlanRequest.duration` | number | No | Desired final duration. The response caps it to the caller's plan. Default: `15`. Minimum: `0.1`. Maximum: `86400`. |
| `CreativePlanRequest.style` | string | No | Built-in style-pack id or auto. Default: `"auto"`. Maximum length: `100`. |
| `CreativePlanRequest.motionIntensity` | `"restrained"` / `"balanced"` / `"energetic"` | No |  |
| `CreativePlanRequest.preferredMedia` | `"image"` / `"video"` / `"mixed"` | No | Default: `"mixed"`. |
| `CreativePlanRequest.recentAssetSlugs` | array of string | No | Recently used creative-library slugs to exclude from fresh or explore work. Maximum items: `20`. |
| `CreativePlanRequest.brand` | [CreativeBrandKit](#schema-creative-brand-kit) | No |  |

**Nested field: `CreativePlanRequest.variationSeed`**

Optional reproducible creative seed.

Exactly one of the listed alternatives must match.

**oneOf alternative 1**

Minimum length: `1`. Maximum length: `128`.

Type: string.

**oneOf alternative 2**

Type: integer.

**Nested field: `CreativePlanRequest.recentAssetSlugs`**

Recently used creative-library slugs to exclude from fresh or explore work.

Maximum items: `20`.

**Array item: `CreativePlanRequest.recentAssetSlugs[]`**

Maximum length: `255`.

Type: string.


### schema creative brand kit

**CreativeBrandKit**


Unknown properties are rejected.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `CreativeBrandKit.name` | string | No | Maximum length: `200`. |
| `CreativeBrandKit.primaryColor` | string | No | Pattern: `^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$`. |
| `CreativeBrandKit.secondaryColor` | string | No | Pattern: `^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$`. |
| `CreativeBrandKit.accentColor` | string | No | Pattern: `^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$`. |
| `CreativeBrandKit.headlineFont` | string | No | Maximum length: `100`. |
| `CreativeBrandKit.bodyFont` | string | No | Maximum length: `100`. |
| `CreativeBrandKit.logoUrl` | string | No | Maximum length: `2048`. Format: `uri`. |


### schema creative plan response

**CreativePlanResponse**


Required properties: `creativePlanVersion`, `request`, `variation`, `directions`, `creativeWorkflow`, `nextActions`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `CreativePlanResponse.creativePlanVersion` | string | Yes |  |
| `CreativePlanResponse.schemaVersion` | string | No |  |
| `CreativePlanResponse.sourceOfTruth` | string | No |  |
| `CreativePlanResponse.planLimits` | object | No |  |
| `CreativePlanResponse.request` | object | Yes |  |
| `CreativePlanResponse.variation` | object | Yes |  |
| `CreativePlanResponse.searchQueries` | object | No |  |
| `CreativePlanResponse.exclusions` | array of string | No |  |
| `CreativePlanResponse.directions` | array of object | Yes | One direction for consistent/fresh or 2-5 materially different directions for explore. |
| `CreativePlanResponse.creativeWorkflow` | object | Yes | Template selection, no-exact-match fallback, anti-repetition, build-order and quality-gate rules. |
| `CreativePlanResponse.nextActions` | array of string | Yes |  |
| `CreativePlanResponse.warnings` | array of string | No |  |

**Nested field: `CreativePlanResponse.exclusions`**

**Array item: `CreativePlanResponse.exclusions[]`**

Type: string.

**Nested field: `CreativePlanResponse.directions`**

One direction for consistent/fresh or 2-5 materially different directions for explore.

**Array item: `CreativePlanResponse.directions[]`**

Type: object.

**Nested field: `CreativePlanResponse.nextActions`**

**Array item: `CreativePlanResponse.nextActions[]`**

Type: string.

**Nested field: `CreativePlanResponse.warnings`**

**Array item: `CreativePlanResponse.warnings[]`**

Type: string.


### schema error

**Error**


Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `Error.error` | string | Yes | Error type |
| `Error.message` | string | No | Human-readable error message |


### schema authentication error

**AuthenticationError**


Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `AuthenticationError.error` | string | Yes | Error type |
| `AuthenticationError.message` | string | No | Human-readable error message |


## Related resources

- [OpenAPI specification](https://docs.zvid.io/openapi.yaml)
- [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json)
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Authentication guide](https://docs.zvid.io/docs/authentication/)