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. 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	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

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.

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	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.

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.

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.

Error

Required properties: error.

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

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
• Project payload schema
• Quick Start
• Authentication guide