# GEN — Auto Content Engine API

> GEN is an autonomous social media agent platform. One API surface takes a raw idea all the way to a published video — agent setup, idea generation with real trending data, vidsheet production, layer composition, render, and publish.

This is a system-prompt style teaching document. Read it top-to-bottom and you will know how to use the GEN API end-to-end. Every workflow follows the same 5-step journey. The docs, the MCP server, and the TypeScript SDK are all organized around these 5 steps.

Base URLs:
- `https://api.gen.pro/v1` — agent setup, vidsheets, generations, renders, publishing, content monitoring
- `https://agent.gen.pro/v1` — content ideas, research, conversations, chat

Auth: `X-API-Key: <your-PAT>` (recommended) or `Authorization: Bearer <jwt>`. Create a PAT in the GEN dashboard: log in > select agent > API page in the sidebar > Create API Key.

---

## The 5-step journey

```
Step 1 — Set Up Your Agent
  ↓
Step 2 — Generate Content Ideas      ← data-driven proposals from 10+ platforms
  ↓
Step 3 — Convert Idea to Vidsheet     ← clone a template (80% path)
  ↓
Step 4 — Edit & Generate              ← cells, layers, creation cards, polling
  ↓
Step 5 — Export & Publish             ← render, download, publish to social
```

Each step produces the input the next step needs. Walk it once to build mental model, then branch freely.

---

## Step 1 — Set Up Your Agent

**What it is.** Configure identity, personality, voice, inspiration sources, and the social accounts the agent posts from. Every downstream feature (ideas, templates, renders) reads from this configuration. A blank agent produces generic output; a richly configured agent produces specific, on-brand output from the very first call.

**Mental model.** Agent Core is one flat endpoint that replaces a dozen separate setup calls. Every field name maps 1:1 to how the GEN Setup canvas saves. Send only the fields you want to change — unknown fields return 422.

**The one call that sets everything up:**

```bash
curl -X PATCH "https://api.gen.pro/v1/agents/$AGENT_ID/core" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "Santiago",
    "description": "San Antonio street food scout who hunts the best tacos.",
    "identity_type": "character",
    "goal": "growth",
    "target_platforms": ["tiktok", "instagram"],
    "shortform": true,
    "keywords": ["streetfood", "foodtruck", "tacotok"],
    "monitored": [
      { "handle": "https://tiktok.com/@keithlee", "item_type": "account" },
      { "handle": "sanantonioeats", "item_type": "hashtag" }
    ],
    "research_topics": [
      { "topic": "new food truck openings in San Antonio" }
    ],
    "linked_accounts": [
      { "url": "https://tiktok.com/@santiago_sa", "platform": "tiktok" }
    ],
    "personality": "Santiago grew up eating at his tia taco stand in south San Antonio...",
    "default_user_voice": { "voice_id": "21m00Tcm4TlvDq8ikWAM", "source": "public" }
  }'
```

Returns `200 OK` on full success, `207 Multi-Status` if some sections fail.

**Three distinctions that trip people up:**
- `linked_accounts` = agent's OWN brand socials (what it posts from). `monitored` = inspiration sources (creators/hashtags/keywords to watch). `research_topics` = expertise areas the platform researches daily. Don't mix them.
- `description` = 2-3 sentence summary (max 500 chars). `personality` = full persona text (max 20000 chars). 3000-char persona in description returns 422.
- `keywords` sent without `monitored` auto-mirrors keywords into monitored with item_type="keyword".

**Voice design.** Agent Core accepts a `default_user_voice` pointing at any voice in the library. To create new voices, use the 4-step prompt-based design flow or clone from an audio sample. See Step 1 endpoints below.

**This call feeds Step 2.** The Ideas Engine reads `keywords`, `monitored`, `research_topics`, and `personality` every run. Configure once, ideas stay on-brand forever.

### Step 1 endpoints

```
GET    /v1/me                                    — current user
GET    /v1/workspaces                            — list workspaces
GET    /v1/agents?workspace_id=                  — list agents

POST   /v1/agents                                — create agent
GET    /v1/agents/:id                            — read agent
PATCH  /v1/agents/:id                            — update agent
DELETE /v1/agents/:id                            — delete agent

GET    /v1/agents/:agent_id/core                 — read flat agent setup
PATCH  /v1/agents/:agent_id/core                 — write any subset

GET    /v1/agents/:agent_id/voice/library        — list voices (filter by source)
POST   /v1/agents/:agent_id/voice/integrations/elevenlabs   — connect user ElevenLabs key
POST   /v1/agents/:agent_id/voice/integrations/elevenlabs/test   — validate without saving
DELETE /v1/agents/:agent_id/voice/integrations/elevenlabs   — disconnect

POST   /v1/agents/:agent_id/voice/design/generate-script        — step 1 (prompt→script)
POST   /v1/agents/:agent_id/voice/design/generate-description   — step 2 (→ style desc)
POST   /v1/agents/:agent_id/voice/design/generate-samples       — step 3 (3 candidates)
POST   /v1/agents/:agent_id/voice/design                        — step 4 (finalize + save)
POST   /v1/agents/:agent_id/voice/clone                         — clone from audio

DELETE /v1/agents/:agent_id/voice/:voice_id                     — delete user-owned voice
POST   /v1/agents/:agent_id/voice/:voice_id/preview             — async TTS preview
GET    /v1/agents/:agent_id/voice/preview/:job_id               — poll preview

GET    /v1/organizations                         — list workspaces
POST   /v1/organizations                         — create workspace
GET    /v1/organizations/:id                     — read (includes credit balance)
PATCH  /v1/organizations/:id                     — update
DELETE /v1/organizations/:id                     — delete (owner only)

POST   /v1/persisted_tokens                      — create API key (token shown once)
GET    /v1/persisted_tokens                      — list
PATCH  /v1/persisted_tokens/:id                  — rename
DELETE /v1/persisted_tokens/:id/revoke           — revoke one
DELETE /v1/persisted_tokens/revoke_all           — revoke all
```

---

## Step 2 — Generate Content Ideas

**What it is.** Ask the agent to propose videos. The Ideas Engine pulls trending data from 10+ platforms (TikTok, Instagram, YouTube, Reddit, X, Hacker News, Perplexity, Gemini), matches it to the agent's configured keywords and inspiration, and returns complete video specs — hook, full script, video type, selected assets, project manifest, rationale.

**Mental model.** Calls are async. POST a natural-language message, get back a `run_id` and `conversation_id`, poll until complete, then read the ideas from the conversation. Refining existing ideas is just another message with the same `conversation_id`. Long-term preferences (applied to all future runs) are set via another message that starts with "remember:".

**Trigger ideas:**

```bash
curl -X POST "https://agent.gen.pro/v1/agent/run" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "message": "Generate 5 content ideas grounded in this week trends"
  }'
# → { "run_id": "run_abc", "conversation_id": "conv_xyz", "status": "running", "firebase_path": "..." }
```

**Poll until done:**

```bash
curl "https://agent.gen.pro/v1/agent/runs/run_abc" \
  -H "X-API-Key: $GEN_API_KEY"
# poll every ~5s until status == "completed"
```

**Read ideas from the conversation:**

```bash
curl "https://agent.gen.pro/v1/agent/conversations/conv_xyz/messages" \
  -H "X-API-Key: $GEN_API_KEY"
```

Each idea in the response includes:
- `title`, `hook`, `full_script`
- `video_type`, `video_type_id`, `estimated_duration`, `aspect_ratio`
- `selected_assets[]` — curated assets (clips + images from research phase) with `url`, `type`, `description`, `usage`, `clip_range`
- `project_manifest` — full video production spec (`total_duration`, `timeline_layers[]`) that slots directly into Step 3
- `inspiration_sources[]` — trending videos that informed the idea
- `rationale`

**Refine specific ideas** (pass the same `conversation_id`):

```bash
curl -X POST "https://agent.gen.pro/v1/agent/run" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "conversation_id": "conv_xyz",
    "message": "Make idea 1 hook punchier. Change idea 3 to montage. Drop idea 5."
  }'
```

**Set persistent preferences** (applied to every future run):

```bash
curl -X POST "https://agent.gen.pro/v1/agent/run" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "message": "remember: always use statement hooks, never questions. target women 25-34."
  }'
```

**Standalone research** (without generating ideas):

```bash
curl -X POST "https://agent.gen.pro/v1/research" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "'"$AGENT_ID"'", "topic": "tariffs on beauty imports 2026", "depth": "default" }'
```

Depths: `quick`, `default`, `deep`. Returns a `run_id`; poll `GET /v1/agent/runs/:run_id` until `completed` to read the structured research findings and summary.

**Trending data** (scrape content into the agent knowledge base):

```bash
curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY" \
  -F 'user_job[user_job_type]=train_social' \
  -F 'user_job[data]={"platform":"tiktok","type":"hashtag","value":"streetfood","days":7,"max_results":50,"monitoring":false}'
```

Supported platforms/types: TikTok (username / hashtag / keyword), Instagram (username / hashtag), YouTube (username / hashtag / keyword). Scraped content is indexed into the agent; query it via agent chat or feed it into the Ideas Engine.

**Three layers of control**:
- Per-batch requirements — "focus on before/after", "under 12 seconds" (this run only)
- Long-term preferences — "remember: always X, never Y" (all future runs)
- Refinement — "make idea 3 punchier" (iterate on specific ideas)

### Step 2 endpoints

```
POST   /v1/agent/run                              — trigger run (ideas/refine/preferences/chat)
GET    /v1/agent/runs/:run_id                     — poll run status
POST   /v1/agent/runs/:run_id/approve             — approve or reject a pending action; body { approved: true|false }

GET    /v1/agent/conversations?agent_id=          — list conversations
GET    /v1/agent/conversations/:id                — read conversation
PATCH  /v1/agent/conversations/:id                — rename / pin
DELETE /v1/agent/conversations/:id                — delete
GET    /v1/agent/conversations/:id/messages       — list messages
GET    /v1/agent/conversations/:id/runs           — list runs

GET    /v1/agent/ideas?agent_id=&status=          — list ideas
POST   /v1/agent/ideas/:id/status                 — cycle to next status
PUT    /v1/agent/ideas/:id/status/:status         — set explicit status

POST   /v1/research                               — standalone research

POST   /v1/user_jobs (train_social)               — start scraping (agent.gen.pro → monitoring)
GET    /v1/user_jobs/:id                          — poll monitoring job
PUT    /v1/user_jobs/:id                          — update monitoring job
```

Idea status flow: `generated` → `approve_to_create` → `ready_for_review` → `approved_to_post` → `posted`.
Edit/rejection statuses: `change_idea`, `change_video`, `rejected`.

Video type IDs: 0=Any, 1=Talking Avatar, 2=Green Screen, 3=Montage, 4=Text-Driven, 5=POV Object, 6=Narrated/VO, 8=Split Screen, 9=Skit.

---

## Step 3 — Convert Idea to Vidsheet

**What it is.** Turn an idea into an **Auto Content Engine** (vidsheet) — a working production surface with rows, columns, cells, and layers. **Cloning a template is the 80% path.** Custom engines are available but 15-25× more API calls.

**Mental model.** Each idea has a `video_type` (`talking_avatar`, `montage`, `split_screen`, etc.). Each template is tagged with the same video types. Match the idea's video type to a template, clone it, and you have a fully configured engine in one call.

**List templates:**

```bash
curl "https://api.gen.pro/v1/templates/projects" \
  -H "X-API-Key: $GEN_API_KEY"
# → [{ slug, title, description, tags, cover, recent_generated_contents }]
```

**Preview a template before cloning:**

```bash
curl "https://api.gen.pro/v1/templates/projects/tiktok-talking-avatar" \
  -H "X-API-Key: $GEN_API_KEY"
```

**Clone the template into your agent** (this is the chain from Step 2):

```bash
curl -X POST "https://api.gen.pro/v1/templates/spreadsheets/tiktok-talking-avatar/clone" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "'"$AGENT_ID"'" }'
# → fully configured engine with columns, rows, cells, layer stack
```

Returns a new engine `id`. Cloning is **free** — no credits consumed.

**Starter templates (pick these 90% of the time):**

- `tiktok-talking-avatar` — Founder-style VO, explainer, testimonial
- `tiktok-montage` — Multi-shot b-roll with music
- `tiktok-vo-broll` — Narrated / voiceover over curated b-roll
- `tiktok-text-driven` — Kinetic text + music, no avatar
- `tiktok-split-screen` — Reaction / comparison
- `ig-reel-story` — Longer 30–60s vertical
- `yt-short-explainer` — 45s explainer with text + VO

**If you really need a custom engine** (rare):

```bash
curl -X POST "https://api.gen.pro/v1/autocontentengine?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spreadsheet": { "title": "Custom campaign" } }'
# then manually create columns, layers, cells — 15-25 more calls
```

### Step 3 endpoints

```
GET    /v1/templates/projects                        — list templates (paginated)
GET    /v1/templates/projects/:slug                  — template details
POST   /v1/templates/spreadsheets/:slug/clone        — clone into agent

POST   /v1/autocontentengine?agent_id=               — create blank engine
GET    /v1/autocontentengine/:id?agent_id=           — read engine with all nested data
POST   /v1/autocontentengine/:id/clone?agent_id=     — clone engine (same or diff agent)
```

---

## Step 4 — Edit & Generate

**What it is.** Fill the vidsheet cells with content. Configure creation cards. Trigger generations. Poll until complete.

**Mental model.** Every cell has exactly one **creation card** — a declaration of how that cell generates content. Every video-role cell has a stack of **layers** that composite into the final video. The 3-call pattern for any cell: (1) PATCH card or cell value, (2) POST generate, (3) GET status until completed.

**Read the full engine:**

```bash
curl "https://api.gen.pro/v1/autocontentengine/$ENGINE_ID?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY"
# includes spreadsheet_columns, spreadsheet_rows, spreadsheet_cells, layers
```

**Drop text into a cell:**

```bash
curl -X PATCH "https://api.gen.pro/v1/autocontentengine/$ENGINE_ID/cells/$CELL_ID?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "spreadsheet_cell": { "value": "The $2 taco at 2am saved my life." } }'
```

**Trigger a cell generation:**

```bash
curl -X POST "https://api.gen.pro/v1/autocontentengine/$ENGINE_ID/cells/$CELL_ID/generate?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_type": "video_from_text",
    "data": {
      "prompt": "San Antonio taco truck at golden hour, steam rising, handheld camera",
      "model": "veo_3",
      "aspect_ratio": "9:16",
      "duration": 10
    }
  }'
# → { "generation_id": 789, "status": "pending" }
```

**Poll until complete:**

```bash
curl "https://api.gen.pro/v1/generations/789" \
  -H "X-API-Key: $GEN_API_KEY"
# status: pending → processing → completed | failed | stopped
# on completed: result (text) or output_resources (media URLs) populated
```

**Stop or continue:**

```bash
curl -X POST "https://api.gen.pro/v1/generations/789/stop"     -H "X-API-Key: $GEN_API_KEY"   # refunds
curl -X POST "https://api.gen.pro/v1/generations/789/continue" -H "X-API-Key: $GEN_API_KEY"   # re-charges
```

**Upload an asset** (for `video_from_image`, `video_from_ingredients`, `lipsync`, `captions`, `media`):

```bash
# Small files (multipart):
curl -X POST "https://api.gen.pro/v1/content_resources?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY" \
  -F "content_resource[file]=@local.mp4"

# Large files (>50 MB, up to 1 GB):
# 1. Get pre-signed S3 URL:
curl -X POST "https://api.gen.pro/v1/direct_upload" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "blob": { "filename": "hero.mp4", "byte_size": 123456789, "checksum": "BASE64MD5==", "content_type": "video/mp4" } }'
# 2. PUT file to returned direct_upload.url
# 3. POST /v1/content_resources with signed_id as content_resource[file]
```

Checksum = `openssl md5 -binary hero.mp4 | base64`. Max 1 GB.

### Step 4 endpoints

```
# Rows
GET    /v1/autocontentengine/:id/rows?agent_id=
POST   /v1/autocontentengine/:id/rows?agent_id=
GET    /v1/autocontentengine/:id/rows/:row_id?agent_id=
POST   /v1/autocontentengine/:id/rows/:row_id/duplicate?agent_id=
PUT    /v1/autocontentengine/:id/rows/update_positions?agent_id=
PUT    /v1/autocontentengine/:id/rows/mass_update?agent_id=

# Columns (ingredient role only; system roles are read-only)
GET    /v1/autocontentengine/:id/columns?agent_id=
POST   /v1/autocontentengine/:id/columns?agent_id=
POST   /v1/autocontentengine/:id/columns/:col_id/duplicate?agent_id=
PATCH  /v1/autocontentengine/:id/columns/update_positions?agent_id=
PUT    /v1/autocontentengine/:id/columns/mass_update?agent_id=

# Cells
GET    /v1/autocontentengine/:id/cells/:cell_id?agent_id=
PATCH  /v1/autocontentengine/:id/cells/:cell_id?agent_id=
PUT    /v1/autocontentengine/:id/cells/mass_update?agent_id=
PATCH  /v1/autocontentengine/:id/cells/:cell_id/set_default_user_job?agent_id=

# Layers
POST   /v1/autocontentengine/:id/cells/:cell_id/layers?agent_id=
GET    /v1/autocontentengine/:id/cells/:cell_id/layers/:layer_id?agent_id=
PATCH  /v1/autocontentengine/:id/cells/:cell_id/layers/:layer_id?agent_id=
DELETE /v1/autocontentengine/:id/cells/:cell_id/layers/:layer_id?agent_id=
POST   /v1/autocontentengine/:id/cells/:cell_id/layers/:layer_id/duplicate?agent_id=
PUT    /v1/autocontentengine/:id/cells/:cell_id/layers/update_positions?agent_id=

# Generations
POST   /v1/autocontentengine/:id/cells/:cell_id/generate?agent_id=
POST   /v1/autocontentengine/:id/cells/:cell_id/layers/:layer_id/generate?agent_id=
GET    /v1/generations/:id
POST   /v1/generations/:id/stop
POST   /v1/generations/:id/continue

# Variables
GET    /v1/autocontentengine/:id/global_variables?agent_id=
POST   /v1/autocontentengine/:id/import_global_variables?agent_id=     (XLSX)
GET    /v1/autocontentengine/global_variables_template                 (download template)

# Content Resources & Assets
GET    /v1/content_resources?agent_id=&type=&page=
POST   /v1/content_resources?agent_id=                                  (multipart)
GET    /v1/content_resources/:id?agent_id=
PATCH  /v1/content_resources/:id?agent_id=
DELETE /v1/content_resources/:id?agent_id=
GET    /v1/asset_libraries?agent_id=&folder_id=&asset_type=&search=
POST   /v1/asset_folders?agent_id=
PATCH  /v1/asset_folders/:id?agent_id=
DELETE /v1/asset_folders/:id?agent_id=
POST   /v1/direct_upload                                                (large files)

# Automation
GET    /v1/agents/:agent_id/automation_config
PATCH  /v1/agents/:agent_id/automation_config
POST   /v1/agents/:agent_id/automation_config/test_webhook
POST   /v1/agents/:agent_id/automation_config/test_callback
```

Column types: `text`, `image`, `video`, `audio`.
Column roles: `ingredient` (user-editable), `video`, `final_video`, `stats`, `global_variable_name`, `global_variable_value` (system-managed).
Only `ingredient` role columns can be created / updated / deleted.

---

## Step 5 — Export & Publish

**What it is.** Composite all layers on the final_video cell into one MP4 (render), download it, optionally publish to TikTok (Instagram / YouTube coming).

**Mental model.** Render is an async generation like any other — trigger it on the final_video cell, poll until completed, then the `output_resources[0].url` is a public CDN URL. Publishing is a user_job that takes a `media_url` (the render URL works directly).

**Render:**

```bash
curl -X POST "https://api.gen.pro/v1/autocontentengine/$ENGINE_ID/cells/$FINAL_VIDEO_CELL_ID/render?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY"
# → { "generation_id": 56789, "status": "pending" }
```

**Poll:**

```bash
curl "https://api.gen.pro/v1/generations/56789" \
  -H "X-API-Key: $GEN_API_KEY"
# pending → processing → completed | failed
# on completed:
# {
#   "id": 56789,
#   "status": "completed",
#   "output_resources": [
#     {
#       "id": 4821,
#       "url": "https://cdn.gen.pro/outputs/render_xyz.mp4",
#       "thumbnail_url": "https://cdn.gen.pro/thumbnails/render_xyz.jpg",
#       "object_type": "video"
#     }
#   ]
# }
```

**Download** (public CDN URL, no auth needed):

```bash
curl -L -o final_video.mp4 "https://cdn.gen.pro/outputs/render_xyz.mp4"
```

**Publish to TikTok now** (chain from the render URL):

```bash
curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_job_type": "publish_content",
    "data": "{\"platform\":\"tiktok\",\"media_url\":\"https://cdn.gen.pro/outputs/render_xyz.mp4\",\"description\":\"The $2 taco at 2am #streetfood #tacotok\",\"schedule_type\":\"now\",\"media_type\":\"VIDEO\"}"
  }'
# → { "user_job_id": 138860 }
```

**Schedule for later:**

```bash
# same body but:
# "schedule_type": "scheduled",
# "scheduled_time": "2026-04-20T15:00:00Z"
```

**Poll publish job:**

```bash
curl "https://api.gen.pro/v1/user_jobs/138860?agent_id=$AGENT_ID" \
  -H "X-API-Key: $GEN_API_KEY"
# pending → processing → completed | failed
# on completed: result.post_id is the TikTok post ID
```

**Prerequisites for publish.** The agent must have a connected TikTok account. The media URL must be publicly accessible at post time.

### Step 5 endpoints

```
POST   /v1/autocontentengine/:id/cells/:cell_id/render?agent_id=   — kick off render
GET    /v1/generations/:id                                          — poll render
POST   /v1/user_jobs?agent_id= (publish_content)                    — publish now / schedule
GET    /v1/user_jobs/:id?agent_id=                                  — poll publish job
```

---

## Starter Templates

Clone one of these via `POST /v1/templates/spreadsheets/:slug/clone`:

- `tiktok-talking-avatar` — founder VO + lipsync + captions. Best for explainer, testimonial, personal brand.
- `tiktok-montage` — multi-shot b-roll stitched with music. Best for product shots, travel, "a day in the life".
- `tiktok-vo-broll` — single narrated voiceover over curated b-roll. Best for news/commentary/explainer.
- `tiktok-text-driven` — kinetic text + music, no avatar. Best for list posts, "3 reasons why", quotes.
- `tiktok-split-screen` — side-by-side reaction / comparison. Best for reviews, before/after, duets.

If none match, build custom with `POST /v1/autocontentengine` and add columns / layers by hand — but template cloning handles 90% of production use cases.

---

## Creation Card Types (all 9)

Every cell generation declares a `generation_type` and `data` object. Models are canonical names — the MCP server and SDK map them to internal Rails names automatically.

### text
```json
{ "generation_type": "text",
  "data": { "prompt": "Write a 12s TikTok hook for {{topic}}", "model": "gemini_2_5_pro", "variables": { "topic": "San Antonio tacos" } } }
```
Models: `gemini_2_0_flash`, `gemini_2_5_pro`, `gpt_4o`, `gpt_4o_mini`, `o3_mini`, `o4_mini`, `claude_sonnet_4`.

### image_from_text
```json
{ "generation_type": "image_from_text",
  "data": { "prompt": "...", "model": "midjourney", "aspect_ratio": "9:16" } }
```
Models: `gemini_image`, `gemini_pro_image`, `midjourney`. Aspect ratios: `1:1`, `9:16`, `16:9`, `4:3`, `3:4`.

### video_from_text
```json
{ "generation_type": "video_from_text",
  "data": { "prompt": "...", "model": "veo_3", "aspect_ratio": "9:16", "duration": 10, "negative_prompt": "no text overlays" } }
```
Models: `veo_3`, `veo_3_fast`, `veo_3_1`, `veo_3_1_fast`, `sora_2`, `kling_1_6`, `seedance_pro`, `seedance_pro_1_5`. Aspect ratios: `1:1`, `9:16`, `16:9`. Duration: 5 or 10.

### video_from_image
```json
{ "generation_type": "video_from_image",
  "data": { "image_resource_id": 4821, "image_tail_resource_id": 4822, "prompt": "...", "model": "kling_2_6", "aspect_ratio": "9:16", "duration": 5 } }
```
Models: `kling_2_1`, `kling_2_6`, `veo_3`, `veo_3_1`, `sora_2`, `seedance_lite`, `seedance_pro`, `seedance_pro_1_5`. `image_tail_resource_id` optional.

### video_from_ingredients
```json
{ "generation_type": "video_from_ingredients",
  "data": { "prompt": "...", "model": "pika", "asset_resource_ids": [4821, 4822, 4823], "aspect_ratio": "9:16", "duration": 5 } }
```
Models: `pika`, `kling_1_6`, `seedance_lite`, `veo_3_1`, `veo_3_1_fast`.

### speech_from_text
```json
{ "generation_type": "speech_from_text",
  "data": { "script": "...", "voice_method": "my_voices", "voice_id": "21m00...", "enhance_voice": true, "speed": 1.0 } }
```
Voice methods: `my_voices` (saved voice), `design_voice` (generate from gender/language description), `clone_voice` (use audio sample: pass `audio_resource_id`).

### lipsync
```json
{ "generation_type": "lipsync",
  "data": { "model": "sync_so", "video_resource_id": 6001, "audio_resource_id": 5921 } }
```
Models: `sync_so`, `gen`.

### captions
```json
{ "generation_type": "captions",
  "data": { "model": "gemini", "source_resource_id": 6001 } }
```

### media (pass-through upload)
```json
{ "generation_type": "media",
  "data": { "content_resource_id": 7000 } }
```
No AI — just attaches an uploaded resource to the cell.

### render (composite)
```
POST /v1/autocontentengine/:id/cells/:cell_id/render?agent_id=
```
No `generation_type` in body. Composites all layers into one final video.

Use canonical generation type names for new integrations.

---

## Error Format

```json
{ "error": "Human-readable message", "error_code": "machine_code" }
```

Common codes:

| Status | Code | Meaning |
|--------|------|---------|
| 401 | `unauthorized` | missing or invalid API key |
| 403 | `forbidden` | no permission for this resource |
| 404 | `not_found` | resource doesn't exist |
| 422 | `usable_gen_credit_required` | workspace has no active credits |
| 422 | `agent_not_found` | invalid `agent_id` |
| 422 | `insufficient_credits_for_job` | not enough credits for this generation |
| 422 | `validation_error` | invalid request body |

---

## Integrations

- MCP Server: `npx @poweredbygen/autocontentengine-mcp-server@latest` (env: `GEN_API_KEY`)
- TypeScript SDK: `npm install @poweredbygen/gen-sdk`
- n8n: HTTP Request node with `X-API-Key` header
- OpenAPI 3.1: https://api.gen.pro/openapi.yaml (every operation tagged with `x-phase`)

## Links

- Full reference: https://api.gen.pro/llms-full.txt
- Docs site (5-step journey): https://api.gen.pro
- Help center: https://docs.gen.pro
- Homepage: https://www.gen.pro