Brand Infinity Engine - API Documentation

Complete API reference for webhooks, database schema, and integration endpoints.

---

📋 Table of Contents

1. Webhook Endpoints
2. Database Schema
3. Utility Functions
4. Integration Examples

---

Webhook Endpoints

All n8n workflows expose webhook endpoints for triggering pipeline stages.

Base URL

http://localhost:5678/webhook/

For production, replace with your n8n instance URL.

---

1. Strategist Pillar

Endpoint: POST /webhook/strategist

Generates creative briefs based on trends, brand guidelines, and competitor analysis.

Request Body

{
  "brand_guideline_id": 1,
  "campaign_goal": "Increase product awareness for Q1 2024",
  "target_platform": "Instagram",
  "budget_range": "medium",
  "target_audience_override": "Tech professionals 25-40"
}

Parameters

Field	Type	Required	Description
brand_guideline_id	integer	Yes	ID from brand_guidelines table
campaign_goal	string	Yes	Campaign objective (max 500 chars)
target_platform	string	No	Platform: Instagram, TikTok, YouTube, LinkedIn, All
budget_range	string	No	low, medium, high, unlimited (default: medium)
target_audience_override	string	No	Override brand's default target audience

Response

{
  "success": true,
  "creative_brief_id": 42,
  "brief": {
    "campaign_concept": "Productivity in Motion: Show how TechFlow transforms chaotic workflows into smooth operations",
    "key_message": "Work flows better with TechFlow",
    "target_emotion": "Relief, empowerment, confidence",
    "visual_direction": "Split-screen comparisons, before/after transitions, smooth animations",
    "cta": "Start your free trial today",
    "platform_specific_notes": "Optimize for Instagram Reels 9:16 aspect ratio, 15-30 second duration"
  },
  "metadata": {
    "trends_analyzed": 5,
    "competitor_ads_reviewed": 3,
    "estimated_cost": "$0.0234"
  }
}

---

2. Copywriter Pillar

Endpoint: POST /webhook/copywriter

Generates scripts, hooks, and scene breakdowns from creative briefs.

Request Body

{
  "creative_brief_id": 42,
  "script_style": "conversational",
  "duration_seconds": 30,
  "include_voiceover": true,
  "hooks_count": 3
}

Parameters

Field	Type	Required	Description
creative_brief_id	integer	Yes	ID from creative_briefs table
script_style	string	No	formal, conversational, humorous, inspirational (default: conversational)
duration_seconds	integer	No	Target duration: 15-120 seconds (default: 30)
include_voiceover	boolean	No	Generate voiceover script (default: true)
hooks_count	integer	No	Number of hook variations: 1-5 (default: 3)

Response

{
  "success": true,
  "script_id": 156,
  "hooks": [
    {
      "hook_id": 201,
      "text": "Ever feel like your work is drowning in chaos?",
      "quality_score": 0.87
    },
    {
      "hook_id": 202,
      "text": "Stop fighting your workflow. Start flowing.",
      "quality_score": 0.92
    },
    {
      "hook_id": 203,
      "text": "What if work actually worked for you?",
      "quality_score": 0.89
    }
  ],
  "script": {
    "full_text": "...",
    "word_count": 87,
    "estimated_duration": 29.5,
    "scenes": [
      {
        "scene_number": 1,
        "duration": 3,
        "visual_description": "Close-up of frustrated person at messy desk",
        "voiceover": "Ever feel like your work is drowning in chaos?",
        "on_screen_text": null
      }
      // ... more scenes
    ]
  },
  "metadata": {
    "quality_score": 0.85,
    "brand_alignment_score": 0.91,
    "estimated_cost": "$0.0456"
  }
}

---

3. Production House Pillar

Endpoint: POST /webhook/production

Generates video scenes using AI video models.

Request Body

{
  "script_id": 156,
  "video_model": "auto",
  "quality": "high",
  "aspect_ratio": "9:16",
  "include_audio": true,
  "tts_voice_id": "your-elevenlabs-voice-id"
}

Parameters

Field	Type	Required	Description
script_id	integer	Yes	ID from scripts table
video_model	string	No	auto, sora, veo3, seedream, nano-b (default: auto)
quality	string	No	low, medium, high, cinematic (default: high)
aspect_ratio	string	No	16:9, 9:16, 1:1, 4:5 (default: 9:16)
include_audio	boolean	No	Generate voiceover (default: true)
tts_voice_id	string	Conditional	Required if include_audio is true

Response

{
  "success": true,
  "video_id": 89,
  "scenes": [
    {
      "scene_id": 301,
      "scene_number": 1,
      "video_url": "https://storage.example.com/videos/scene_301.mp4",
      "thumbnail_url": "https://storage.example.com/thumbnails/scene_301.jpg",
      "duration": 3.2,
      "status": "completed",
      "model_used": "veo3"
    }
    // ... more scenes
  ],
  "audio": {
    "audio_asset_id": 45,
    "url": "https://storage.example.com/audio/voiceover_45.mp3",
    "duration": 29.8,
    "model_used": "eleven_multilingual_v2"
  },
  "metadata": {
    "total_duration": 30.0,
    "scenes_count": 8,
    "estimated_cost": "$12.45",
    "generation_time_seconds": 180
  }
}

---

4. Campaign Manager Pillar

Endpoint: POST /webhook/campaign

Creates campaigns with A/B testing variants.

Request Body

{
  "video_id": 89,
  "campaign_name": "TechFlow Q1 2024 - Instagram Reels",
  "variants_count": 3,
  "test_hooks": true,
  "test_cta": true
}

Parameters

Field	Type	Required	Description
video_id	integer	Yes	ID from videos table
campaign_name	string	Yes	Campaign name (max 255 chars)
variants_count	integer	No	Number of A/B test variants: 1-5 (default: 1)
test_hooks	boolean	No	Create variants with different hooks (default: false)
test_cta	boolean	No	Create variants with different CTAs (default: false)

Response

{
  "success": true,
  "campaign_id": 23,
  "variants": [
    {
      "variant_id": 67,
      "variant_name": "Variant A - Original",
      "video_url": "https://storage.example.com/campaigns/variant_67.mp4",
      "hook_id": 201,
      "modifications": {}
    },
    {
      "variant_id": 68,
      "variant_name": "Variant B - Alt Hook",
      "video_url": "https://storage.example.com/campaigns/variant_68.mp4",
      "hook_id": 202,
      "modifications": {
        "hook_text": "Stop fighting your workflow. Start flowing."
      }
    },
    {
      "variant_id": 69,
      "variant_name": "Variant C - Alt Hook 2",
      "video_url": "https://storage.example.com/campaigns/variant_69.mp4",
      "hook_id": 203,
      "modifications": {
        "hook_text": "What if work actually worked for you?"
      }
    }
  ],
  "metadata": {
    "total_cost": "$13.20",
    "estimated_reach": "10K-50K"
  }
}

---

5. Broadcaster Pillar

Endpoint: POST /webhook/broadcast

Publishes or schedules campaigns to social media platforms.

Request Body

{
  "campaign_id": 23,
  "platforms": ["instagram", "tiktok"],
  "schedule": {
    "type": "scheduled",
    "publish_at": "2024-02-15T10:00:00Z",
    "timezone": "America/New_York"
  },
  "caption": "Transform your workflow with TechFlow 🚀 #Productivity #WorkSmarter",
  "hashtags": ["#TechFlow", "#Productivity", "#SaaS"]
}

Parameters

Field	Type	Required	Description
campaign_id	integer	Yes	ID from campaigns table
platforms	array	Yes	Array of: instagram, tiktok, youtube, linkedin
schedule.type	string	No	immediate, scheduled (default: immediate)
schedule.publish_at	string (ISO 8601)	Conditional	Required if type is scheduled
schedule.timezone	string	No	IANA timezone (default: UTC)
caption	string	Yes	Post caption (max 2200 chars)
hashtags	array	No	Array of hashtags (including #)

Response

{
  "success": true,
  "publication_id": 45,
  "posts": [
    {
      "platform_post_id": 101,
      "platform": "instagram",
      "status": "scheduled",
      "scheduled_for": "2024-02-15T10:00:00Z",
      "post_url": null,
      "variant_id": 67
    },
    {
      "platform_post_id": 102,
      "platform": "tiktok",
      "status": "scheduled",
      "scheduled_for": "2024-02-15T10:00:00Z",
      "post_url": null,
      "variant_id": 67
    }
  ],
  "metadata": {
    "scheduled_posts_count": 2,
    "estimated_publish_time": "2024-02-15T10:00:00Z"
  }
}

---

Database Schema

Pillar 1: Strategist

trends

Trending topics and viral content from various platforms.

CREATE TABLE trends (
    trend_id SERIAL PRIMARY KEY,
    trend_text TEXT NOT NULL,
    platform VARCHAR(50),
    virality_score DECIMAL(3,2),
    relevance_score DECIMAL(3,2),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

Columns:

• trend_id: Unique identifier
• trend_text: The trending topic or content description
• platform: Where the trend was found (Twitter, TikTok, Instagram, etc.)
• virality_score: 0.00-1.00, how viral/popular the trend is
• relevance_score: 0.00-1.00, relevance to brand/industry
• metadata: Additional data like hashtags, view counts, engagement

brand_guidelines

Brand identity, tone, visual style, and values.

CREATE TABLE brand_guidelines (
    brand_guideline_id SERIAL PRIMARY KEY,
    brand_name VARCHAR(255) NOT NULL,
    industry VARCHAR(255),
    tone TEXT,
    visual_style TEXT,
    target_audience TEXT,
    core_values JSONB,
    embedding vector(1536),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

Columns:

• brand_guideline_id: Unique identifier
• brand_name: Company or brand name
• industry: Business sector
• tone: Desired communication tone (e.g., "professional yet approachable")
• visual_style: Visual aesthetic description
• target_audience: Target demographic
• core_values: JSON array of brand values
• embedding: Vector embedding for RAG retrieval (1536 dimensions for OpenAI)
• metadata: Logo URLs, colors, fonts, etc.

competitor_ads

Competitor advertising content and performance data.

CREATE TABLE competitor_ads (
    competitor_ad_id SERIAL PRIMARY KEY,
    competitor_name VARCHAR(255),
    ad_content TEXT,
    platform VARCHAR(50),
    engagement_score DECIMAL(3,2),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

creative_briefs

Strategic campaign concepts generated from trends + brand + competitors.

CREATE TABLE creative_briefs (
    creative_brief_id SERIAL PRIMARY KEY,
    brand_guideline_id INTEGER REFERENCES brand_guidelines(brand_guideline_id),
    campaign_concept TEXT NOT NULL,
    key_message TEXT,
    target_emotion TEXT,
    visual_direction TEXT,
    cta TEXT,
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

---

Pillar 2: Copywriter

scripts

Video scripts with scenes and timing.

CREATE TABLE scripts (
    script_id SERIAL PRIMARY KEY,
    creative_brief_id INTEGER REFERENCES creative_briefs(creative_brief_id),
    full_text TEXT NOT NULL,
    word_count INTEGER,
    estimated_duration DECIMAL(5,2),
    quality_score DECIMAL(3,2),
    brand_alignment_score DECIMAL(3,2),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

hooks

Attention-grabbing opening lines.

CREATE TABLE hooks (
    hook_id SERIAL PRIMARY KEY,
    creative_brief_id INTEGER REFERENCES creative_briefs(creative_brief_id),
    hook_text TEXT NOT NULL,
    quality_score DECIMAL(3,2),
    created_at TIMESTAMP DEFAULT NOW()
);

scene_segments

Individual scenes with visual descriptions and voiceovers.

CREATE TABLE scene_segments (
    scene_id SERIAL PRIMARY KEY,
    script_id INTEGER REFERENCES scripts(script_id),
    scene_number INTEGER,
    duration DECIMAL(5,2),
    visual_description TEXT,
    voiceover TEXT,
    on_screen_text TEXT,
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

---

Pillar 3: Production House

videos

Master video records.

CREATE TABLE videos (
    video_id SERIAL PRIMARY KEY,
    script_id INTEGER REFERENCES scripts(script_id),
    title VARCHAR(255),
    total_duration DECIMAL(5,2),
    aspect_ratio VARCHAR(10),
    status VARCHAR(50),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

Status values: pending, in_progress, completed, failed

scenes

Generated video scenes with storage URLs.

CREATE TABLE scenes (
    scene_id SERIAL PRIMARY KEY,
    video_id INTEGER REFERENCES videos(video_id),
    scene_segment_id INTEGER REFERENCES scene_segments(scene_id),
    scene_number INTEGER,
    video_url TEXT,
    thumbnail_url TEXT,
    duration DECIMAL(5,2),
    model_used VARCHAR(50),
    status VARCHAR(50),
    created_at TIMESTAMP DEFAULT NOW()
);

generation_jobs

Tracks asynchronous video generation jobs.

CREATE TABLE generation_jobs (
    job_id SERIAL PRIMARY KEY,
    scene_id INTEGER REFERENCES scenes(scene_id),
    model VARCHAR(50),
    status VARCHAR(50),
    progress_percentage INTEGER,
    error_message TEXT,
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

audio_assets

Voiceovers and audio tracks.

CREATE TABLE audio_assets (
    audio_asset_id SERIAL PRIMARY KEY,
    video_id INTEGER REFERENCES videos(video_id),
    audio_url TEXT,
    duration DECIMAL(5,2),
    model_used VARCHAR(50),
    created_at TIMESTAMP DEFAULT NOW()
);

---

Pillar 4: Campaign Manager

campaigns

Marketing campaigns with metadata.

CREATE TABLE campaigns (
    campaign_id SERIAL PRIMARY KEY,
    video_id INTEGER REFERENCES videos(video_id),
    campaign_name VARCHAR(255),
    status VARCHAR(50),
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

variants

A/B test variants of campaigns.

CREATE TABLE variants (
    variant_id SERIAL PRIMARY KEY,
    campaign_id INTEGER REFERENCES campaigns(campaign_id),
    variant_name VARCHAR(255),
    video_url TEXT,
    hook_id INTEGER REFERENCES hooks(hook_id),
    modifications JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

cost_ledger

Tracks all API costs.

CREATE TABLE cost_ledger (
    cost_id SERIAL PRIMARY KEY,
    entity_type VARCHAR(50),
    entity_id INTEGER,
    operation VARCHAR(100),
    provider VARCHAR(50),
    model VARCHAR(100),
    cost_usd DECIMAL(10,4),
    metadata JSONB,
    timestamp TIMESTAMP DEFAULT NOW()
);

entity_type: script, video, scene, audio, campaign

---

Pillar 5: Broadcaster

publications

Publication batches to multiple platforms.

CREATE TABLE publications (
    publication_id SERIAL PRIMARY KEY,
    campaign_id INTEGER REFERENCES campaigns(campaign_id),
    status VARCHAR(50),
    scheduled_for TIMESTAMP,
    published_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

platform_posts

Individual posts per platform.

CREATE TABLE platform_posts (
    platform_post_id SERIAL PRIMARY KEY,
    publication_id INTEGER REFERENCES publications(publication_id),
    platform VARCHAR(50),
    variant_id INTEGER REFERENCES variants(variant_id),
    post_url TEXT,
    status VARCHAR(50),
    error_message TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

Platforms: instagram, tiktok, youtube, linkedin, blotato

engagement_metrics

Real-time engagement tracking.

CREATE TABLE engagement_metrics (
    metric_id SERIAL PRIMARY KEY,
    platform_post_id INTEGER REFERENCES platform_posts(platform_post_id),
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    saves INTEGER,
    engagement_rate DECIMAL(5,2),
    recorded_at TIMESTAMP DEFAULT NOW()
);

---

Utility Functions

Brand Validator

const BrandValidator = require('./utils/brand_validator');

const validator = new BrandValidator(vectorDbClient, openaiApiKey);

const result = await validator.validateContent(
    "Check out our amazing new product!",
    brandGuidelineId
);

console.log(result.isValid);  // true/false
console.log(result.score);    // 0.0-1.0
console.log(result.suggestions);  // Array of improvement suggestions

Cost Calculator

const CostCalculator = require('./utils/cost_calculator');

const calculator = new CostCalculator();

const cost = calculator.calculateTextCost(
    'openai',
    'gpt-4o',
    1500,  // input tokens
    500    // output tokens
);

console.log(calculator.formatCost(cost));  // "$0.0125"

Quality Scorer

const QualityScorer = require('./utils/quality_scorer');

const scorer = new QualityScorer(openaiApiKey);

const result = await scorer.scoreContent(
    "Your script text here...",
    'script'
);

console.log(result.overallScore);  // 0.0-1.0
console.log(result.rating);        // "Excellent", "Good", etc.
console.log(result.suggestions);   // Improvement suggestions

Model Router

const ModelRouter = require('./utils/model_router');

const router = new ModelRouter();

const selected = router.selectTextModel({
    complexity: 'high',
    budget: 'medium',
    priority: 'quality',
    task: 'creative'
});

console.log(selected.model);    // "gpt-4o"
console.log(selected.reason);   // Explanation

---

Integration Examples

Node.js

const axios = require('axios');

// Generate creative brief
const response = await axios.post('http://localhost:5678/webhook/strategist', {
    brand_guideline_id: 1,
    campaign_goal: "Increase Q1 signups",
    target_platform: "Instagram"
});

const briefId = response.data.creative_brief_id;

// Generate script
const scriptResponse = await axios.post('http://localhost:5678/webhook/copywriter', {
    creative_brief_id: briefId,
    duration_seconds: 30
});

console.log('Script generated:', scriptResponse.data.script_id);

Python

import requests

# Full pipeline execution
n8n_base = "http://localhost:5678/webhook"

# Step 1: Creative brief
brief_resp = requests.post(f"{n8n_base}/strategist", json={
    "brand_guideline_id": 1,
    "campaign_goal": "Product launch campaign",
    "target_platform": "TikTok"
})
brief_id = brief_resp.json()["creative_brief_id"]

# Step 2: Script
script_resp = requests.post(f"{n8n_base}/copywriter", json={
    "creative_brief_id": brief_id,
    "hooks_count": 3
})
script_id = script_resp.json()["script_id"]

# Step 3: Production
video_resp = requests.post(f"{n8n_base}/production", json={
    "script_id": script_id,
    "quality": "high"
})
video_id = video_resp.json()["video_id"]

print(f"Video generated: {video_id}")

cURL

# One-liner campaign creation
curl -X POST http://localhost:5678/webhook/strategist \
  -H "Content-Type: application/json" \
  -d '{"brand_guideline_id": 1, "campaign_goal": "Q1 Launch", "target_platform": "Instagram"}'

---

Next: Troubleshooting Guide