AI Generation

All generation endpoints require authentication and deduct credits from your balance. Insufficient credits returns a 402 response.

Generate Ad Copy

Generates 5 platform-optimized copy variants. Synchronous — returns results immediately.

POST /api/generate/copy
Authorization: Bearer <token>
Content-Type: application/json

{
  "projectId": "uuid",
  "productId": "uuid",
  "platform": "meta",
  "format": "short",
  "tone": "bold",
  "customInstructions": "Focus on the summer sale",
  "idempotencyKey": "user-session-abc123"
}

Field	Type	Required	Options
projectId	uuid	Yes	—
productId	uuid	Yes	—
platform	string	Yes	meta, tiktok, google, linkedin, pinterest, universal
format	string	Yes	short, long, hook, story
tone	string	Yes	professional, casual, urgent, luxe, playful, bold
customInstructions	string	No	Max 500 chars
idempotencyKey	string	No	Max 128 chars

Response (200): 1 credit deducted

{
  "jobId": "uuid",
  "status": "completed",
  "creditsUsed": 1,
  "creditsRemaining": 24,
  "variants": [
    {
      "hook": "Summer just got hotter.",
      "body": "Our best-selling widget is now 50% off...",
      "cta": "Shop the Sale",
      "hashtags": ["#SummerSale", "#LimitedTime"]
    }
  ]
}

Generate Static Ad

Creates an AI-generated ad image. Asynchronous — returns a job ID for polling.

POST /api/generate/static-ad
Authorization: Bearer <token>
Content-Type: application/json

{
  "projectId": "uuid",
  "productId": "uuid",
  "style": "modern",
  "aspectRatio": "1:1",
  "prompt": "Summer vibes, bright background",
  "idempotencyKey": "static-abc123"
}

Field	Type	Required	Options
projectId	uuid	Yes	—
productId	uuid	Yes	—
style	string	No	product_hero, lifestyle, minimal, bold, seasonal
aspectRatio	string	No	1:1, 9:16, 4:5, 16:9 (default: 1:1)
prompt	string	No	5-1000 chars
idempotencyKey	string	No	Max 128 chars

Response (200): 3 credits deducted

{
  "jobId": "uuid",
  "status": "queued",
  "creditsUsed": 3,
  "creditsRemaining": 21
}

Generate UGC Video

Creates an AI avatar video with lip-synced speech. Asynchronous — typically takes 1-3 minutes.

POST /api/generate/video
Authorization: Bearer <token>
Content-Type: application/json

{
  "projectId": "uuid",
  "productId": "uuid",
  "script": "Hey! You need to check out this amazing product...",
  "avatarUrl": "https://example.com/avatar.jpg",
  "voiceId": "male-1",
  "aspectRatio": "9:16",
  "idempotencyKey": "video-abc123"
}

Field	Type	Required	Options
projectId	uuid	Yes	—
productId	uuid	Yes	—
script	string	Yes	10-2000 chars
avatarUrl	url	No	Custom avatar image
voiceId	string	No	Default: male-1
aspectRatio	string	No	9:16, 1:1, 16:9 (default: 9:16)
idempotencyKey	string	No	Max 128 chars

Response (200): 40 credits deducted

{
  "jobId": "uuid",
  "status": "queued",
  "creditsUsed": 40,
  "creditsRemaining": 60
}

Poll Job Status

Check the status of an async generation job.

GET /api/generate/status?jobId=<uuid>
Authorization: Bearer <token>

Response (200):

{
  "id": "uuid",
  "type": "static_ad",
  "status": "completed",
  "assets": [
    { "id": "uuid", "type": "image", "url": "https://..." }
  ],
  "createdAt": "2026-03-09T10:00:00Z",
  "completedAt": "2026-03-09T10:00:25Z"
}

Job Statuses

Status	Meaning
pending	Created, not yet queued
queued	In the processing queue
processing	Actively being generated
completed	Done — assets available
failed	Error occurred (credits refunded)
canceled	Canceled by user or admin
expired	Timed out

Idempotency

All generation endpoints accept an optional idempotencyKey. If a non-terminal job exists with the same key for your user, the existing job is returned instead of creating a new one — no duplicate credit charge.

// First request: creates job, deducts credits
{ "idempotencyKey": "my-key-123", ... }
// Response: { "jobId": "abc", "creditsUsed": 3 }

// Duplicate request: returns existing job, 0 credits
{ "idempotencyKey": "my-key-123", ... }
// Response: { "jobId": "abc", "creditsUsed": 0, "status": "reused" }

Error Responses

Status	Meaning
400	Invalid input (Zod validation error)
401	Not authenticated
402	Insufficient credits
404	Product or project not found