# Brand Overlays API Documentation > LLM-optimized documentation for Brand Overlays. Copy into your AI assistant for integration help. ## Overview **Model ID:** `brand-overlay` **Type:** Video Generation **Credit Cost:** 2 credits per video Add a hook title, a lower-third callout, a review card, a progress bar, a countdown timer, a price tag, an offer badge and a branded end card to any video. Exact text in your brand color. ## Endpoint ``` POST https://pixeldojo.ai/api/v1/models/brand-overlay/run ``` ## Authentication All requests require an API key in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` Get your API key: https://pixeldojo.ai/api-platform/api-keys ## Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `video` | url | Yes | - | Reference video URL. | | `color` | string | No | - | Brand color as #RRGGBB: fills the offer badge and the CTA button. Defaults to #FFE500. | | `hook_text` | string | No | - | Hook title for the first seconds, 5-8 words, e.g. "Octopuses have THREE hearts?". | | `hook_duration` | number | No | - | Seconds the hook stays. Defaults to 2.5. (min: 1, max: 6) | | `callout_title` | string | No | - | Lower third: a benefit ("Ships in 24h") or a name. | | `callout_subtitle` | string | No | - | Second line under the label, e.g. a title or detail. | | `callout_style` | enum | No | - | label (default): a brand-colored box. classic: the broadcast lower third, an accent bar beside a bold name and a lighter title (bottom band on 16:9). (Options: label, classic) | | `callout_start` | number | No | - | Second the label slides in. Defaults to 3. (min: 0, max: 600) | | `callout_duration` | number | No | - | Seconds it stays. Defaults to 4. (min: 1, max: 10) | | `review_quote` | string | No | - | Review card quote, e.g. "Best mug I have ever owned". | | `review_name` | string | No | - | Who said it, e.g. "Jess, verified buyer". | | `review_stars` | integer | No | - | Stars on the review card. Defaults to 5. (min: 1, max: 5) | | `review_start` | number | No | - | Second the review card appears. Defaults to just after the hook. (min: 0, max: 600) | | `review_duration` | number | No | - | Seconds it stays. Defaults to 4. (min: 1, max: 10) | | `progress_bar` | boolean | No | - | A thin bar in the brand color across the top that fills as the video plays. | | `countdown_from` | string | No | - | Countdown start, e.g. "23:59:59"; the digits tick down each second it is on screen. | | `countdown_label` | string | No | - | Words above the timer. Defaults to "Ends in". | | `countdown_start` | number | No | - | Second the timer appears. Defaults to 0.5, or just after the hook. (min: 0, max: 600) | | `countdown_duration` | number | No | - | Seconds it stays. Defaults to 4. (min: 1, max: 10) | | `price_now` | string | No | - | Price tag, the price to pay, e.g. "$49". | | `price_was` | string | No | - | Old price, shown struck through, e.g. "$79". | | `price_label` | string | No | - | Small line under the price, e.g. "Today only". | | `price_start` | number | No | - | Second the tag appears. Defaults to just after the hook. (min: 0, max: 600) | | `price_duration` | number | No | - | Seconds it stays. Defaults to 4. (min: 1, max: 10) | | `offer_text` | string | No | - | Offer callout headline, e.g. "50% OFF". | | `offer_subtext` | string | No | - | Small line under the offer, e.g. "This week only". | | `offer_start` | number | No | - | Second the offer appears. Defaults to 0.5, or just after the hook. (min: 0, max: 600) | | `offer_duration` | number | No | - | Seconds the callout stays. Defaults to 3. (min: 1, max: 10) | | `offer_position` | enum | No | - | top (default) or bottom, above where captions sit. (Options: top, bottom) | | `end_headline` | string | No | - | End card headline. Setting it adds the end card. | | `end_cta` | string | No | - | End card button text, e.g. "Shop now". | | `end_url` | url | No | - | End card web address, e.g. "pixeldojo.ai". | | `logo_url` | url | No | - | End card logo: a PNG (transparent works best) or JPG URL. | | `end_duration` | number | No | - | Seconds the end card holds after the video. Defaults to 3. (min: 2, max: 5) | ## Quick Start ### 1. Submit a Job ```bash curl -X POST "https://pixeldojo.ai/api/v1/models/brand-overlay/run" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "video": "https://...", "color": "#39E508", "offer_text": "50% OFF", "offer_subtext": "This week only", "end_headline": "Your new favorite mug", "end_cta": "Shop now", "end_url": "example.com" }' ``` **Response:** ```json { "jobId": "job_abc123...", "status": "pending", "statusUrl": "https://pixeldojo.ai/api/v1/jobs/job_abc123", "creditCost": 2, "creditsRemaining": 95 } ``` ### 2. Poll for Results ```bash curl "https://pixeldojo.ai/api/v1/jobs/job_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Completed Response:** ```json { "jobId": "job_abc123...", "status": "completed", "output": { "video": "https://temp.pixeldojo.ai/..." }, "creditCost": 2 } ``` ## Python Example ```python import requests import time API_KEY = "YOUR_API_KEY" # Submit job response = requests.post( "https://pixeldojo.ai/api/v1/models/brand-overlay/run", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }, json={ "video": "https://...", "color": "#39E508", "offer_text": "50% OFF", "offer_subtext": "This week only", "end_headline": "Your new favorite mug", "end_cta": "Shop now", "end_url": "example.com" } ) job = response.json() job_id = job["jobId"] # Poll for completion while True: status_response = requests.get( f"https://pixeldojo.ai/api/v1/jobs/{'{job_id}'}", headers={"Authorization": f"Bearer {API_KEY}"} ) status = status_response.json() if status["status"] == "completed": print("Output:", status["output"]) break elif status["status"] == "failed": print("Error:", status.get("error")) break time.sleep(2) ``` ## JavaScript Example ```javascript const API_KEY = 'YOUR_API_KEY'; // Submit job const submitResponse = await fetch('https://pixeldojo.ai/api/v1/models/brand-overlay/run', { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "video": "https://...", "color": "#39E508", "offer_text": "50% OFF", "offer_subtext": "This week only", "end_headline": "Your new favorite mug", "end_cta": "Shop now", "end_url": "example.com" }) }); const job = await submitResponse.json(); // Poll for completion const pollForResult = async (jobId) => { while (true) { const statusResponse = await fetch(`https://pixeldojo.ai/api/v1/jobs/${jobId}`, { headers: { 'Authorization': `Bearer ${API_KEY}` } }); const status = await statusResponse.json(); if (status.status === 'completed') return status.output; if (status.status === 'failed') throw new Error(status.error); await new Promise(r => setTimeout(r, 2000)); } }; const output = await pollForResult(job.jobId); console.log('Output:', output); ``` ## Use Saved Characters (@Name) This model takes no reference images, so `@Name` of a saved character is refused (400) before anything is charged. A saved location, prop or style with a description is inserted as text. For saved characters, use a model that takes reference images, such as Nano Banana Pro or Seedream 5 for images, or Seedance 2.5 or WAN 3.0 for video. ## Error Codes | Code | Status | Description | |------|--------|-------------| | `unauthorized` | 401 | Invalid or missing API key | | `insufficient_credits` | 402 | Not enough credits | | `invalid_request` | 400 | Invalid parameters | | `model_not_found` | 404 | Model ID not found | | `internal_error` | 500 | Server error | ## Links - **Full Documentation:** https://pixeldojo.ai/api-platform/brand-overlay - **API Keys:** https://pixeldojo.ai/api-platform/api-keys - **Buy Credits:** https://pixeldojo.ai/api-platform/buy-credits - **All Models:** https://pixeldojo.ai/api/v1/models - **OpenAPI Spec:** https://pixeldojo.ai/api/openapi