---
title: "Plan a creative video"
method: POST
path: "/api/render/creative-plan/api-key"
tags: ["Authoring"]
---

# Plan a creative video

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

## Request

- Base URL: `https://api.zvid.io`
- URL: `https://api.zvid.io/api/render/creative-plan/api-key`
- Auth: API key in header `x-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.

## Request body

- CreativePlanRequest
  - `brief` string, required: What the video should communicate, for whom, and the desired outcome.
  - `variationMode` 'consistent' | 'fresh' | 'explore': Stable repeatable output, one new direction, or 2-5 materially different directions.
  - `variationSeed` union: Optional reproducible creative seed.
    - string
    - integer
  - `exploreCount` integer
  - `aspectRatio` '16:9' | '9:16' | '1:1' | '4:5' | 'custom'
  - `duration` number: Desired final duration. The response caps it to the caller's plan.
  - `style` string: Built-in style-pack id or auto.
  - `motionIntensity` 'restrained' | 'balanced' | 'energetic'
  - `preferredMedia` 'image' | 'video' | 'mixed'
  - `recentAssetSlugs` string[]: Recently used creative-library slugs to exclude from fresh or explore work.
  - `brand` CreativeBrandKit
    - `name` string
    - `primaryColor` string
    - `secondaryColor` string
    - `accentColor` string
    - `headlineFont` string
    - `bodyFont` string
    - `logoUrl` string, uri

## Response `200`

Creative plan generated

- CreativePlanResponse
  - `creativePlanVersion` string, required
  - `schemaVersion` string
  - `sourceOfTruth` string
  - `planLimits` object
  - `request` object, required
  - `variation` object, required
  - `searchQueries` object
  - `exclusions` string[]
  - `directions` object[], required: One direction for consistent/fresh or 2-5 materially different directions for explore.
  - `creativeWorkflow` object, required: Template selection, no-exact-match fallback, anti-repetition, build-order and quality-gate rules.
  - `nextActions` string[], required
  - `warnings` string[]

## Other responses

- `400`: Invalid creative brief or options
- `401`: Unauthorized
- `500`: Internal server error

---

[API](https://skmtc.dev/zvid/apis/zvid-api.md) · [All operations](https://skmtc.dev/zvid/apis/zvid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zvid/apis/zvid-api/revisions/8a665b293b37?raw)