---

## InVideo API — Core Endpoints

**Base URL:** `https://api.invideo.io/v1`

All requests require:

| Endpoint | Method | Purpose |
|---|---|---|
| `/videos/generate` | POST | Start video generation from a script or brief |
| `/videos/{id}/status` | GET | Poll generation progress |
| `/videos/{id}/export` | GET | Retrieve final download URL |
| `/scripts/generate` | POST | Generate an ad script from a brief (if supported) |

---

## Ad Script Structures (Claude Will Apply These)

Claude selects the right copywriting framework automatically based on the campaign goal:

| Framework | Best For | Structure |
|---|---|---|
| **AIDA** | Awareness campaigns | Attention → Interest → Desire → Action |
| **PAS** | Pain-point products | Problem → Agitate → Solution |
| **BAB** | Transformation products | Before → After → Bridge |
| **Hook + Proof + CTA** | Performance ads | Bold hook → Social proof → Offer + CTA |

---

## Examples

### Generate a Facebook Ad from a Brief

---

### Generate Platform-Specific Ad Variants

---

### Poll All Variants Until Ready

---

### A/B Test: Generate 3 Hook Variations

---

## Full Brief-to-Ad Pipeline

When given an ad brief, Claude will:

1. **Extract** product, audience, goal, tone, benefit, offer, and CTA from the brief
2. **Choose** the right copywriting framework (AIDA, PAS, BAB, Hook+Proof+CTA)
3. **Write** a platform-optimized ad script (15–30s for social, up to 60s for YouTube)
4. **Select** format, style, voice, music mood, and caption style per platform
5. **Generate** all required format variants in parallel via InVideo API
6. **Poll** until all variants are ready
7. **Return** download URLs and a structured ad delivery report

---

## Platform Ad Specifications

| Platform | Format | Duration | Key Requirements |
|---|---|---|---|
| Facebook Feed | 1:1 or 16:9 | 15–30s | Captions mandatory (85% watched muted) |
| Instagram Feed | 1:1 | 15–30s | Hook in first 2s, strong visual |
| Instagram Stories | 9:16 | 15s | Full screen, bold captions, fast pace |
| Instagram Reels Ads | 9:16 | 15–30s | Native feel, no borders |
| YouTube Pre-roll | 16:9 | 15–30s | Skip button at 5s — hook must hit before |
| YouTube Bumper | 16:9 | 6s max | One message, one CTA only |
| TikTok Ads | 9:16 | 15–60s | Authentic tone, trending audio |

---

## Normalized Ad Output Schema

---

## Ad Copywriting Best Practices (Applied Automatically)

- **Hook in the first 2 seconds** — the scroll stops here or nowhere
- **Lead with the problem or benefit** — never with the brand name
- **One clear message per ad** — don't try to say everything at once
- **Always include social proof** — numbers, testimonials, or results
- **End with a specific, urgent CTA** — "Download free today" beats "Learn more"
- **Write for silent viewing** — assume 85% of viewers have sound off on Facebook
- **Match the platform energy** — polished for YouTube, raw and native for TikTok

---

## Error Handling

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.invideo.io/v1',
  headers: { Authorization: `Bearer ${process.env.INVIDEO_API_KEY}` }
});

// Define the ad brief
const brief = {
  product: "AI-powered meal planning app",
  targetAudience: "busy professionals aged 25–40",
  goal: "app installs",
  tone: "energetic and relatable",
  keyBenefit: "save 2 hours a week on meal prep",
  offer: "Free 14-day trial, no credit card required",
  callToAction: "Download free today"
};

// Claude-generated script based on the brief (PAS framework)
const script = `
  Tired of staring at the fridge every evening, clueless about dinner?
  That mental load of planning meals every single day is exhausting.
  Meet MealAI — the app that plans your entire week in 30 seconds.
  Personalized to your diet, your schedule, your grocery budget.
  Over 200,000 busy professionals already saved 2 hours a week.
  Try it completely free for 14 days. No credit card needed.
  Download MealAI today.
`;

const response = await client.post('/videos/generate', {
  script,
  format: "1:1",              // Square — best for Facebook/Instagram Feed
  duration: "short",          // 15–30 seconds optimal for paid ads
  style: "cinematic",         // polished, professional ad look
  voiceover: {
    enabled: true,
    voice: "en-US-female-1",
    speed: 1.05,
    tone: "energetic"
  },
  captions: {
    enabled: true,
    style: "bold-center",
    highlight: true,
    fontSize: "large"          // readable on mobile without sound
  },
  music: {
    enabled: true,
    mood: "upbeat",
    volume: 0.2
  },
  cta: {
    enabled: true,
    text: "Download Free Today",
    position: "bottom",
    style: "button"
  },
  branding: {
    watermark: false
  }
});

const videoId = response.data.videoId;
console.log("Ad generation started:", videoId);

// Generate all 3 formats from the same script in parallel

const formats = [
  { name: "facebook_feed",    format: "1:1",   platform: "Facebook Feed" },
  { name: "instagram_story",  format: "9:16",  platform: "Instagram Story/Reels" },
  { name: "youtube_preroll",  format: "16:9",  platform: "YouTube Pre-roll" }
];

const jobs = await Promise.all(
  formats.map(f =>
    client.post('/videos/generate', {
      script,
      format: f.format,
      duration: f.format === "16:9" ? "medium" : "short",
      style: "cinematic",
      voiceover: { enabled: true, voice: "en-US-female-1", speed: 1.05 },
      captions: { enabled: true, style: "bold-bottom", highlight: true },
      music: { enabled: true, mood: "upbeat", volume: 0.2 },
      cta: { enabled: true, text: "Try Free Today", position: "bottom" }
    }).then(res => ({ ...f, videoId: res.data.videoId }))
  )
);

console.log("All ad variants started:");
jobs.forEach(j => console.log(`  [${j.platform}] ID: ${j.videoId}`));

async function waitForAll(jobs) {
  const results = [];

  for (const job of jobs) {
    let exportUrl = null;

    while (!exportUrl) {
      await new Promise(r => setTimeout(r, 5000));
      const { data } = await client.get(`/videos/${job.videoId}/status`);

      console.log(`[${job.platform}] ${data.state} — ${data.progress}%`);

      if (data.state === "completed") exportUrl = data.exportUrl;
      if (data.state === "failed") throw new Error(`${job.platform} ad failed`);
    }

    results.push({ ...job, exportUrl });
  }

  return results;
}

const completedAds = await waitForAll(jobs);
completedAds.forEach(ad => {
  console.log(`✅ ${ad.platform}: ${ad.exportUrl}`);
});