---
title: "Start a blueprint run (server-side recipe pipeline)"
method: POST
path: "/v1/blueprints/{slug}/runs"
---

# Start a blueprint run (server-side recipe pipeline)

`POST /v1/blueprints/{slug}/runs`

## Request

- Base URL: `https://api.ffmpeg-micro.com`
- URL: `https://api.ffmpeg-micro.com/v1/blueprints/{slug}/runs`
- Auth: HTTP bearer

Kick off a blueprint recipe as a background pipeline. Available slugs: `product-ad` (generative; charges tokens server-side, 402 when the balance is insufficient), `caption-video` (transcribe then burn; pauses at `awaiting_review` for transcript edits), `viral-short` (optional audio swap then hook overlay), `quote-card` (styled quote card on the dark background; no media input required), `watermark` (logo overlay at a chosen corner and size), `resize-format` (reframe to a target aspect by pad or crop). Inputs are URLs from the upload chain (`gs://` in the upload bucket) or public HTTPS URLs. Poll `GET /v1/blueprints/runs/{id}` for progress; runs continue in the background after the client disconnects.

## Path parameters

- `slug` 'product-ad' | 'caption-video' | 'viral-short' | 'quote-card' | 'watermark' | 'resize-format', required

## Request body

- object: Per-slug inputs. product-ad: `logo_url`, `photo_url`, optional `music_url`. caption-video: `video_url`, optional `language`, `style`. viral-short: `video_url`, `hook_text`, optional `style`, `music_url`. quote-card: `quote`, optional `name`, `handle`, `photo_url` (profile photo; initials avatar without it). watermark: `video_url`, `logo_url`, optional `position` (top-left|top-right|bottom-left|bottom-right|center, default bottom-right), `size` (small|medium|large, default small). resize-format: `video_url`, optional `format` (9x16|1x1|16x9|4x5, default 9x16), `fit` (pad|crop, default pad).
  - `logo_url` string
  - `photo_url` string
  - `video_url` string
  - `hook_text` string
  - `quote` string
  - `name` string
  - `handle` string
  - `position` string
  - `size` string
  - `format` string
  - `fit` string
  - `language` string
  - `style` string
  - `music_url` string

## Response `201`

Run created (pipeline executing in the background)

- object
  - `id` string, uuid
  - `status` string
  - `blueprint` string
  - `tokens_charged` integer

## Other responses

- `400`: Invalid or missing inputs
- `401`: Missing/invalid API key
- `402`: Insufficient token balance (generative blueprints)
- `404`: Unknown blueprint slug
- `429`: Too many active generative runs for this account
- `500`: Unexpected error

---

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