Developer documentation

Brand-Pipe API

One HTTPS call turns a raw clip into a platform-ready video: fitted to 9:16, 1:1 or 16:9, with your logo, loudness normalised to −14 LUFS, optionally with burned-in captions. This page is the complete reference.

1. Get a key

Check out the free tier (25 credits, no card). After checkout you accept the terms and your key is shown once. Keys start with bp_. Store it in a secret manager or your automation tool's credential store.

2. Process a clip

curl -X POST https://api.brand-pipe.com/v1/process \
  -H "X-API-Key: $BRAND_PIPE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/raw.mp4",
    "logo_url": "https://example.com/logo.png",
    "format": "vertical"
  }'

3. Download the result

{
  "success": true,
  "data": {
    "job_id": "6bbee170c2a54f0b9c1e…",
    "result_url": "https://…/6bbee170….mp4?X-Amz-Signature=…",
    "duration_s": 10.0,
    "had_audio": true,
    "format": "vertical",
    "video_reencoded": true,
    "source_color_warning": null,
    "audio_normalized": true,
    "audio_skip_reason": null
  },
  "error": null
}

result_url is a signed link, valid for one hour. The file itself is deleted after 24 hours, so download it or hand it straight to your upload step.

Authentication

Send your key in the X-API-Key header on every request.

X-API-Key: bp_your_key

• Missing or invalid key → 401.
• Key has no credits left → 402. Buy a top-up with the same email; the credits land on the key you already have.
• Rate limit: 300 requests per minute per key, status polls included → 429. Back off and retry.
• Lost key: keys are not stored in plaintext. Email support@brand-pipe.com and you get a new key with your remaining credits.

Response envelope

Every response, including errors and unexpected failures, is JSON with the same three fields. Branch on success, not only on the HTTP status.

{ "success": false, "data": null, "error": "No credits left on this API key." }

Process a video (synchronous)

Downloads the source, renders it and answers with the result in the same request, typically within seconds. Use it for short clips. For anything longer, or for clients with short timeouts, use POST /v1/jobs.

Headers

Request body

All URLs must point to public hosts. Private, loopback, link-local and cloud metadata addresses are rejected with 400, including when a redirect leads there.

Response data

Submit an async job

Takes the same body as /v1/process, plus an optional callback_url. It answers in well under a second and renders in the background. The credit is charged when the job is accepted and refunded if it fails.

curl -X POST https://api.brand-pipe.com/v1/jobs \
  -H "X-API-Key: $BRAND_PIPE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-2026-09-16-001" \
  -d '{
    "video_url": "https://example.com/long-recording.mp4",
    "start_s": 30,
    "duration_s": 240,
    "background": "blur",
    "callback_url": "https://hooks.example.com/brand-pipe"
  }'

{
  "success": true,
  "data": {
    "job_id": "3f9c1a…",
    "status": "queued",
    "status_url": "https://api.brand-pipe.com/v1/jobs/3f9c1a…"
  },
  "error": null
}

Jobs are never dropped under load. They wait in a queue and start as capacity frees up.

Get job status

Polling costs nothing, but it counts toward the rate limit. An interval of 5–10 seconds is plenty. Only the key that submitted a job can read it; any other key gets 404. Each poll signs a fresh result_url, so a workflow that comes back hours later still gets a working link, as long as that is within 24 hours.

{
  "success": true,
  "data": {
    "job_id": "3f9c1a…",
    "status": "done",
    "result_url": "https://…signed…",
    "duration_s": 240.0,
    "had_audio": true,
    "format": "vertical",
    "video_reencoded": true,
    "source_color_warning": null,
    "audio_normalized": true,
    "audio_skip_reason": null,
    "error": null,
    "credits_refunded": false,
    "callback_delivered": true
  },
  "error": null
}

A failed job has result_url: null, the same public message in data.error that the synchronous endpoint would have returned, and credits_refunded: true. The request itself still answers 200 with success: true, because the status was read successfully. Check data.status.

Callbacks

Pass callback_url to POST /v1/jobs and you do not have to poll. When the job reaches done or failed, Brand-Pipe POSTs the job status to that URL: the same object as data in GET /v1/jobs/{id}, without the envelope.

• Content-Type: application/json, User-Agent: BrandPipe/….
• Any 2xx counts as delivered. A network error or 5xx is retried once after 2 seconds; a 4xx is final. Redirects are not followed.
• The URL must be public, and it is checked again at delivery time.
• The outcome is recorded as callback_delivered on the job, so polling remains a fallback if your endpoint was down.

Idempotency & retries

Networks drop responses, and automation tools retry. Send an Idempotency-Key header on either POST endpoint and a repeat of the same request returns the first result instead of rendering and charging again. Keys belong to your API key and are remembered for 24 hours.

Use a value that is unique per item. In n8n that is {{ $execution.id }}-{{ $itemIndex }}. The execution id alone gives every item of a multi-item run the same key, and only the first item would be rendered.

The guarantee covers retries, which always arrive after the first attempt has ended. Two identical requests sent at the same moment can both run.

Burned-in captions

Send an SRT or WebVTT file you already have, such as the output of your transcription step, and it is rendered into the picture. Brand-Pipe does not transcribe.

{
  "video_url": "https://example.com/raw.mp4",
  "subtitles": "1\n00:00:00,500 --> 00:00:02,800\nThree tips for better Shorts\n"
}

n8n

Three ready-made workflows are available on the website: n8n-brand-pipe.json (process and download), n8n-brand-pipe-youtube.json (schedule, generate, process, upload to YouTube) and n8n-brand-pipe-jobs.json (async job for long clips, the callback resumes a Wait node).

1. Create a Header Auth credential named Brand-Pipe API Key with header name X-API-Key and your key as the value.
2. In the HTTP Request node, add the header Idempotency-Key = {{ $execution.id }}-{{ $itemIndex }} and enable Retry On Fail.
3. For long clips, use POST /v1/jobs and follow it with a Wait node set to Resume: On Webhook Call, HTTP method POST. Send {{ $execution.resumeUrl }} as callback_url, and set Limit Wait Time so the execution cannot hang forever. n8n-brand-pipe-jobs.json is exactly that, with a timeout branch that reads the status URL. The resume URL has to be reachable from the internet (n8n Cloud is; a local instance needs a public WEBHOOK_URL), otherwise the API rejects it at submission.

Code examples

Submit an async job and poll until it is finished.

import os, time, httpx

API = "https://api.brand-pipe.com"
HEADERS = {"X-API-Key": os.environ["BRAND_PIPE_KEY"]}

def render(video_url: str, idempotency_key: str) -> str:
    r = httpx.post(f"{API}/v1/jobs", headers={**HEADERS, "Idempotency-Key": idempotency_key},
                   json={"video_url": video_url, "format": "vertical"}, timeout=30)
    body = r.json()
    if not body["success"]:
        raise RuntimeError(f"{r.status_code}: {body['error']}")
    status_url = body["data"]["status_url"]

    while True:
        job = httpx.get(status_url, headers=HEADERS, timeout=30).json()["data"]
        if job["status"] == "done":
            return job["result_url"]
        if job["status"] == "failed":
            raise RuntimeError(job["error"])
        time.sleep(5)

const API = "https://api.brand-pipe.com";
const headers = { "X-API-Key": process.env.BRAND_PIPE_KEY, "Content-Type": "application/json" };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function render(videoUrl, idempotencyKey) {
  const res = await fetch(`${API}/v1/jobs`, {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": idempotencyKey },
    body: JSON.stringify({ video_url: videoUrl, format: "vertical" }),
  });
  const body = await res.json();
  if (!body.success) throw new Error(`${res.status}: ${body.error}`);

  for (;;) {
    const { data: job } = await (await fetch(body.data.status_url, { headers })).json();
    if (job.status === "done") return job.result_url;
    if (job.status === "failed") throw new Error(job.error);
    await sleep(5000);
  }
}

API=https://api.brand-pipe.com
STATUS_URL=$(curl -s -X POST $API/v1/jobs \
  -H "X-API-Key: $BRAND_PIPE_KEY" -H 'Content-Type: application/json' \
  -d '{"video_url":"https://example.com/raw.mp4","format":"vertical"}' | jq -r .data.status_url)

while :; do
  JOB=$(curl -s "$STATUS_URL" -H "X-API-Key: $BRAND_PIPE_KEY")
  STATUS=$(echo "$JOB" | jq -r .data.status)
  [ "$STATUS" = done ] && { echo "$JOB" | jq -r .data.result_url; break; }
  [ "$STATUS" = failed ] && { echo "$JOB" | jq -r .data.error >&2; exit 1; }
  sleep 5
done

Limits

Processing runs in Frankfurt (Google Cloud); results are stored on Cloudflare R2 in the EU jurisdiction.

Credits & refunds

• 1 credit per video, whatever its length. 2 credits with captions.
• Credits are charged when a request is accepted, and refunded automatically if the download, encode or upload fails afterwards. The error response then carries data.credits_refunded: true; failed jobs show the same field.
• Requests rejected up front (invalid body, blocked URL, bad key) are never charged. A source too large for the endpoint is charged and refunded at once.
• One exception: an encode that runs into the processing time limit keeps its credit (credits_refunded: false). The estimate refuses almost every such source before work starts; what remains is a source that is far denser than it declares.
• Status polls and idempotent replays are free.
• Credits never expire. Top-ups bought with the same email land on your existing key.

Errors

The error field carries the message shown here. Stack traces and internal details are never returned.

Questions or something not covered here? support@brand-pipe.com