Try for free

B-Roll API

Send a subject. Get back real, verified photos and footage of exactly it, with the license and credit line on every shot. Use it from REST or from an agent over MCP.

Base URL: https://clypmint.com/api/v1/broll

OpenAPI file for Postman or a generated client. Python: pip install "git+https://github.com/nuttallp/clypmint-broll#subdirectory=python"

Get an API keyTry it live

Auth

Make a key in the dashboard. It starts with cm_live_ and is shown once. Send it as a bearer token on every request.

Header
Authorization: Bearer cm_live_YOUR_KEY

Keep the key on your server or in your agent’s settings. Never put it in a web page.

Plan

POST/api/v1/broll/plan

Send a whole script. We pick the moments that need a cutaway, name the words each one starts on, and find shots for each. Each moment that finds a shot counts as one search.

Body

FieldTypeNotes
transcriptstringThe script or transcript. Up to 40,000 characters. Send this or words.
wordsarray of { text, start, end }Word timings in seconds. With them, every beat comes back with its time in at.
max_beatswhole number, 1 to 20Default 8. The most cutaway moments to find.
results_per_beatwhole number, 1 to 5Default 3.

Request

JSON
{
  "words": [
    { "text": "Notion", "start": 0.4, "end": 0.8 },
    { "text": "launched", "start": 0.8, "end": 1.2 },
    { "text": "in", "start": 1.2, "end": 1.3 },
    { "text": "San", "start": 1.3, "end": 1.6 },
    { "text": "Francisco", "start": 1.6, "end": 2.2 }
  ],
  "max_beats": 8,
  "results_per_beat": 3
}

Response

200 OK
{
  "request_id": "0b7e4c1a-52de-4a8b-8a30-5f2b7c9d1e66",
  "beats": [
    {
      "quote": "Notion launched in San Francisco",
      "at": { "start": 0.4, "end": 2.2 },
      "query": "Notion",
      "why": "A named app. Show the real product.",
      "interpreted": { "subject": "Notion", "kind": "app", "entity": null, "look_for": "The Notion app on screen" },
      "results": [ /* shots, same fields as search */ ]
    }
  ],
  "took_ms": 9800,
  "usage": {
    "billed_searches": 0,
    "searches": 1,
    "free_searches_left_this_month": 98,
    "price_per_search_usd": 0.02
  }
}

Each beat has the quote it starts on, at (start and end in seconds, when you sent word timings), the query we used and its results. If your free searches or your cap run out mid-plan, the remaining beats come back with no results and a withheld reason.

Usage

GET/api/v1/broll/usage

This month’s searches, what is free, what is billed and your cap.

200 OK
{
  "month": "2026-10",
  "searches": 42,
  "free_searches_included": 100,
  "free_searches_left": 58,
  "billed_searches": 0,
  "billed_usd": 0,
  "price_per_search_usd": 0.02,
  "pay_as_you_go": false,
  "monthly_cap_usd": null,
  "billing_url": "https://clypmint.com/broll/dashboard"
}

Errors

Errors come back as { "error": { "code", "message" } } with the HTTP status below.

StatusCodeMeaning
400invalid_requestA field is missing or wrong. The message names it.
401unauthorizedThe key is missing, wrong or turned off.
402free_allowance_usedThe 100 free searches are used. Turn on pay as you go.
402monthly_cap_reachedYou reached your monthly cap. Raise it in the dashboard.
402payment_neededBilling needs attention. Update your card in the dashboard.
409idempotency_key_reusedThat Idempotency-Key was used for a different request. Send a new key.
409request_in_progressA request with that key is still running. Retry in a few seconds.
429too_many_in_flightToo many searches are running at once on this account. Wait for some to finish.
503unavailableA source or the checker is busy. Try again in a moment.
402
{
  "error": {
    "code": "free_allowance_used",
    "message": "You used your 100 free searches this month. Turn on pay as you go at https://clypmint.com/broll/dashboard."
  }
}

Pricing and limits

  • 100 searches a month are free. No card.
  • After that, $0.02 for each search that finds a shot.
  • A search that finds nothing is never billed.
  • A search whose shots could not be checked (verified: false) is never billed either.
  • Pay as you go turns on with a card through Stripe. It is billed monthly for what you used. The default monthly cap is $50, and you can change it in the dashboard.
  • limit is 1 to 10 for search and results_per_beat is 1 to 5 for plan. A plan finds 1 to 20 moments.

Idempotency

Add an Idempotency-Key header (8 to 64 letters, numbers, _, . or -) to make a retry safe. A repeat of the same key returns the first answer and is never billed twice. A key sent with a different request is refused.

Header
Idempotency-Key: render-4821-beat-3

MCP

Server: https://clypmint.com/mcp/broll (Streamable HTTP). It uses the same cm_live_ key as a bearer token. Three tools: find_broll, plan_broll and broll_usage.

claude mcp add --transport http clypmint-broll https://clypmint.com/mcp/broll --header "Authorization: Bearer cm_live_YOUR_KEY"

For Codex, set CLYPMINT_API_KEY in your shell. The open-source client and agent skill are on GitHub.

Local CLI

Platform video and live websites are not served by us. A shot with delivery of local_cut or local_capture carries a cut_command. Run it and the file is made on your own machine.

Cut a clip

bash
npx -y github:nuttallp/clypmint-broll#v1.0.0 cut <url> --start 0 --duration 4

--start is the second to begin at. --duration is how many seconds to keep.

Record a real website

bash
npx -y github:nuttallp/clypmint-broll#v1.0.0 capture <site> --duration 5

This records the live site for the number of seconds you give.

Licensing

Every shot has a license object. Read it before you publish.

  • name and url say which license applies.
  • When attribution has a line, use it as the credit in your video or its description.
  • commercial_use: true means the license allows it. false means it does not.
  • commercial_use: null means the rights belong to the owner. Ask them, or choose another shot.
  • official: true means the shot comes from the subject’s own site or official channel.

This page is a guide, not legal advice.