---
title: "Create Clip Banner"
method: POST
path: "/runs/{run_id}/clips/{clip_id}/banner"
---

# Create Clip Banner

`POST /runs/{run_id}/clips/{clip_id}/banner`

## Request

- Base URL: `https://www.clipzyn.com/v1`
- URL: `https://www.clipzyn.com/v1/runs/{run_id}/clips/{clip_id}/banner`
- Auth: HTTP bearer

Burn ONE banner onto an ALREADY-FINISHED clip's vertical master (or its
16:9 render) and select it (v2 §4.6). The text is server-resolved from the
clip's persisted hooks by lane and rank; client-supplied text is ignored.
This does not consume finishing quota, because a burn is CPU-only, and an
already-burned variant is reused at $0 (reused:true). Recover from
scope_missing by minting a finish:write key, run_not_ready by polling
progress until the run completes, run_not_found or clip_not_found by listing
your runs and their clips, and validation_error (an unknown hook, or a
basic-family style whose banner is engine-owned) by fixing lane, rank, or
target. For rate_limited or service_unavailable, wait retry_after_sec and
retry once.

## Path parameters

- `run_id` string, required
- `clip_id` string, required

## Request body

- BannerBurnRequest: v2 §4.6 burn: a hook address (lane+rank) from the clip's PERSISTED set; the text is server-resolved (client text never reaches the burn). ``target`` picks the finished 9:16 master (default) or the plain 16:9 render.
  - `lane` 's' | 'q', required
  - `rank` integer, required
  - `target` 'vertical' | 'r169'

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

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