Playbook

Watches a video and returns a shoot-ready plan: the transcript, the hook, a scene map, a remake script, a shot list, editing guidance and experiments to try. $0.20 per call. Typically 50 to 90 seconds. Set your client timeout to 300 seconds.

Request

string

required

Link to the video. TikTok, Douyin, Instagram Reels and YouTube Shorts are accepted, including short share links.

string

en, zh-Hans, or zh-Hant. Defaults to the video’s market: Douyin videos come back in Simplified Chinese, everything else in English. See Markets.

Response

object

What was analyzed.

Show reel

string

Provider id, namespaced for non-TikTok platforms.

string

Canonical permalink.

string

tiktok or douyin.

string | null

Creator handle.

string | null

Post caption.

number | null

Full runtime.

string

The language the playbook was written in.

number | null

How many seconds were actually watched. Videos longer than 120 seconds are clipped to the first 120 rather than rejected.

object

The document itself.

Show playbook

number

Schema version. Currently 2.

object

What the video is and who it is for.

object

The opening and why it holds attention.

object

Timestamped spoken content.

array

Scene-by-scene map with timings.

array

On-screen text and when it appears.

object

Cut rhythm and duration.

object

The repeatable format underneath this specific video.

object

The remake plan: script, shot list, setup, editing guide, caption, CTA.

array

Variations worth testing.

array

What would not transfer to a different brand.

Example

curl -X POST https://nouvelhq.com/api/v1/playbook \
  -H "Authorization: Bearer $NOUVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@creator/video/7412345678901234567"}'

curl -X POST https://nouvelhq.com/api/v1/playbook \
  -H "Authorization: Bearer $NOUVEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.douyin.com/video/7615947954167303458"}'

const playbook = await fetch('https://nouvelhq.com/api/v1/playbook', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.NOUVEL_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ url: reelUrl, language: 'zh-Hant' }),
  signal: AbortSignal.timeout(300_000),
}).then((r) => r.json())

Response (truncated)

{
  "reel": {
    "id": "7412345678901234567",
    "url": "https://www.tiktok.com/@creator/video/7412345678901234567",
    "market": "tiktok",
    "authorHandle": "creator",
    "caption": "the only routine that fixed my oily skin",
    "durationSec": 28
  },
  "language": "en",
  "analyzedSeconds": 28,
  "playbook": {
    "version": 2,
    "tier": "advanced",
    "hook": { "text": "Stop using mattifying products", "why": "Contradicts the obvious advice" },
    "scenes": [{ "start": 0, "end": 3, "description": "Close-up on the product, no speech" }],
    "playbook": {
      "script": [{ "t": 0, "line": "Stop using mattifying products." }],
      "shotList": ["0-3s: product close-up, handheld, window light"],
      "caption": "The routine that actually worked",
      "cta": "Comment ROUTINE and I'll send the list"
    }
  }
}

Notes

Every API playbook is full depth. There is no reduced tier out here.
Videos over 120 seconds are clipped, never rejected. analyzedSeconds tells you what was covered, and nothing in the document describes footage beyond it.
Unsupported links return 400 invalid_request; a valid link to a missing or video-less post returns 404 not_found.

Getting started

Concepts

API reference

Request

Response

Example

Notes

​Request

​Response

​Example

​Notes

Request

Response

Example

Notes