Gentic Creative — Documentation
Connect any AI agent to generate brand ad creatives up to 4K resolution and short video clips — search 20,000+ vectorized ads from the top 1,000 ecom brands for inspiration, overlay your own brand images, vectorize product photos, and search your visual library — all through the Model Context Protocol.
1. Getting Started
Sign Up & Get Your API Key
Before you can use Gentic Creative, you need an API key to authenticate your requests.
- Go to gentic.co/creative and create an account.
- Create an organization from your dashboard. API keys and billing are scoped to the organization.
- Generate an API key and use it as a Bearer token in your MCP client.
2. Connecting to the MCP Server
The server is available at https://mcp.gentic.co/creative. For Claude Code:
claude mcp add gentic-creative \
--transport http \
https://mcp.gentic.co/creative \
--header "Authorization: Bearer YOUR_API_KEY"For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).
3. Agent Skill
For the best results, pair the MCP server with the Gentic Creative agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.
Add the skill directly via URL:
https://gentic.co/creative/SKILL.mdOr upload a .skill bundle to Claude Managed Agents:
https://gentic.co/creative/gentic-creative.skillDownload this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.
4. When to Apply
- User wants to generate ad images or static creative assets.
- User wants to generate short (4–8s) AI video clips.
- User wants to create ads inspired by another brand's style from the Meta Ad Library.
- User wants to upload or vectorize product photos into a searchable catalog.
- User wants to search their product image catalog by text description.
- User wants to check the status of ongoing image or video generation jobs.
- User wants to browse or search competitor brand ads for inspiration.
- User wants to extract a brand's guidelines (colors, typography, voice, imagery, aesthetic) from its public website, or look up a previously extracted record.
5. Workflow
1. Capture brand guidelines before generating (optional but recommended)
Before generating assets for a brand, check for an existing brand guidelines record with `get_brand_guidelines` (free) — pass either a `domain` or `url`. If nothing comes back, run `extract_brand_guidelines` (**$3/call, async**) which crawls the brand's public site, combines HTML/CSS parsing with vision-model analysis, and writes a canonical structured document (colors, typography, voice, imagery, aesthetic direction, heritage, generative guardrails — each field has source + confidence + evidence). Pass `webhook_url` to run async and avoid blocking. Once saved, `get_brand_guidelines` is free forever, and the returned fields should inform prompts and `brand_image_urls` on `generate_ad_asset`.
2. Build the product catalog first (recommended)
`vectorize_product_images` is **5¢/image**, accepts 1–50 images per call, and is **async** (images become searchable in ~1–2 minutes). Each image needs a public `image_url`; `product_name` is optional — AI vision auto-generates one if omitted. Upserts on `image_url`, so re-vectorizing updates rather than duplicates. This catalog feeds every subsequent `generate_ad_asset` call via `brand_image_urls`.
3. Search inspiration ads before generating
`search_inspiration_ads` is free and queries a curated library of 20k+ ads scraped from the Meta Ad Library. Describe the style in natural language ("minimalist skincare on white background", "bold fitness ad with athlete"). Filter by `brand_name`, `category` (e.g. "Health/beauty"), or `platform` (`FACEBOOK`/`INSTAGRAM`). Returns ads ranked by visual similarity with copy + metadata. **Use the returned `image_url` values as `inspiration_image_urls` when calling `generate_ad_asset`** — the AI emulates visual aesthetic only, not content.
4. Find product images with `search_product_images`
Free. Describe what you're looking for in natural language ("blue athletic sneakers", "summer beach accessories"). Returns catalog results ranked by relevance with similarity scores. Use the `image_url` values as `brand_image_urls` when generating ads, or as `reference_image_urls` when generating video clips.
5. Generate ad images — $1/image, async
`generate_ad_asset` is **$1 per generated image**. Use `count` (1–10) to batch in parallel — cheaper than calling the tool multiple times. Two modes: (1) standard from `prompt` + optional `brand_image_urls`, or (2) inspiration-based by also passing `inspiration_image_urls` (0–5 refs). Aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default 1:1). `image_size` is 1K/2K/4K (default 4K). Choose the backing model with `image_model` — `nano_banana` (default) is faster and cheaper; `gpt_image_2` is stronger on text rendering and brand consistency. When you pick `gpt_image_2`, the `quality` param (`low`/`medium`/`high`/`auto`) tunes fidelity vs. speed; **it defaults to `medium` to keep OpenAI costs in check — pass `high` explicitly for hero or final creative.** `quality` is ignored on the `nano_banana` path. Unknown `image_model` values fall back to `nano_banana` silently, so existing calls keep working. **Generation is async** — tell the user images are processing; they'll receive an email notification when the job completes. For automation, pass `webhook_url` for a POST callback.
6. Generate video clips — ~$1.50–$10 each
`generate_video_clip` uses Google Veo 3.1 for 4–8s clips. **Fast quality** is ~$1.50–3 (default), **full quality** is ~$5–10 (required for 1080p/4k and for 2–3 reference images). Surface the cost before running — videos can get expensive fast. Key params: `aspect_ratio` (16:9 or 9:16), `duration` (4/6/8, default 8), `resolution` (720p/1080p/4k), `tone` (luxurious/playful/cinematic/etc), `platform` (instagram_reels/tiktok/youtube_preroll/youtube_shorts for pacing). `enhance_prompt` defaults true — even a simple prompt gets transformed into a detailed cinematic one automatically. **Takes 1–6 minutes**; the user gets an email with a preview when it's done.
7. Track jobs with `list_asset_jobs`
Free. Filter by `status` (`processing`/`completed`/`failed`) and `type` (`image`/`video`). Default returns the 20 most recent. When presenting completed jobs, show the asset URLs, group multiple assets as a numbered list, and for in-progress ones remind the user they'll get an email when done.
8. Use webhooks for automation
Both `generate_ad_asset` and `generate_video_clip` accept a `webhook_url` param. When the job completes, the URL receives a POST with `{ job_id, status, type, asset_url, mime_type, prompt, enhanced_prompt, aspect_ratio, duration_seconds, resolution, error }`. Use this for n8n/Zapier/Make pipelines — no polling required.
9. Present results clearly
Don't dump raw JSON. For completed generations, show the asset URLs prominently (rendered inline if the client supports it). Echo back what the user asked for (prompt, aspect ratio, count). When multiple assets are returned, present them as a numbered list. When jobs are still processing, say so explicitly and point at the email notification so the user doesn't keep refreshing.
6. Tool Reference
11 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.
edit_video
Edit a video in one call: remove sentences, move a sentence to the front, change speed, adjust volume, burn auto-generated captions, and/or overlay promotional badges (text or image) at fixed positions — any combination of these in a single call. Returns a job_id immediately. The user receives an email notification when the edit completes; use list_asset_jobs to check status and get the download URL.
| Parameter | Type | Description |
|---|---|---|
video_urlrequired | string | HTTPS URL of the source video (MP4, must have audio for sentence-targeted edits and captions) |
remove_sentence_textsrequired | string[] | List of sentences to cut from the video. Each is matched against the transcript via exact → fuzzy → LLM tiers. The matched span is removed; output duration shrinks by the sum of removed spans. default: [] |
move_to_front_sentence_text | string | A single sentence to pull to the very start of the video ("hook to the front"). Cannot overlap with any remove. Total duration unchanged by this op. |
speed_factor | number | Speed multiplier (0.5x–4.0x). 1.5 plays 50% faster, 0.75 plays 25% slower. Pitch is preserved. 0.5 – 4 |
target_duration_seconds | number | Alternative to speed_factor: target output duration. The worker resolves the speed factor from current_duration / target. Pass at most one of speed_factor or target_duration_seconds. |
gain_db | number | Audio gain in decibels. +6 ≈ 2× linear, -6 ≈ 0.5× linear. 0 dB is pass-through (no effect). -30 – 30 |
add_captionsrequired | boolean | Burn reels-style captions (auto-generated from the cached transcript) into the video. White text + black outline, bottom-third position. Requires audio. default: false |
badges | object[] | Promotional badges to overlay on the output. Each badge is either text OR an image (mutually exclusive). Up to 5 badges per call, all rendered in a single ffmpeg pass. |
webhook_url | string | Optional webhook URL to receive a POST when the edit completes. Same payload shape as generate_video_clip. |
extract_brand_guidelines
Extract comprehensive, production-grade brand guidelines from a brand's public website. Crawls key pages, captures screenshots, and combines HTML/CSS parsing with vision-model analysis to produce a canonical brand document with colors, typography, voice, imagery, aesthetic direction, heritage, and generative guardrails. Every field includes source, confidence, and evidence. Pass webhook_url for async execution.
| Parameter | Type | Description |
|---|---|---|
urlrequired | string | The brand's public website URL. Homepage is always crawled; sub-pages auto-selected from links. |
brand_name | string | Optional override. If omitted, extracted from meta tags / <title>. |
force_refreshrequired | boolean | If true, bypass the 30-day cache and run a fresh extraction. Default false. default: false |
webhook_url | string | If provided, the tool returns immediately with a job_id and POSTs results here on completion. |
depthrequired | integer | Max number of pages to crawl. Default 4 (homepage + about + product + collection). Capped at 6. 1 – 6 · default: 4 |
fetch_page
Fetch a web page and extract its readable text content. Use this to pull brand information from a company website or product details from a product page.
| Parameter | Type | Description |
|---|---|---|
urlrequired | string | URL to fetch and extract text from |
generate_ad_asset
Generate ad images asynchronously. Supports batch generation — use the 'count' parameter to generate multiple images in one call (e.g. count=5 for 5 images). Do NOT call this tool multiple times to generate multiple images; instead, call it once with the desired count. Optionally provide inspiration_image_urls with competitor/reference ads to emulate their style. Returns job_id(s) immediately. The user will receive an email notification when the job completes. Use list_asset_jobs to check status and results.
| Parameter | Type | Description |
|---|---|---|
promptrequired | string | Detailed text prompt describing the ad image to generate |
inspiration_image_urlsrequired | string[] | 0-5 reference/competitor ad URLs to use as style inspiration. The AI will emulate the visual style, layout, and aesthetic of these images — but NOT copy their content. default: [] |
brand_image_urlsrequired | string[] | 0-5 brand asset URLs (product photos, logos) to incorporate into the generated image default: [] |
aspect_ratiorequired | string | Aspect ratio for the generated image enum: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 · default: "1:1" |
image_size | string | Image resolution: 1K (1024px), 2K (2048px), or 4K (4096px). Default is '4K' for nano_banana (Gemini credits are abundant so we want the best output) and '2K' for gpt_image_2 (OpenAI bills steeply at 2880×2880 — pass '4K' explicitly only when the user asks for a large/print-quality output). enum: 1K, 2K, 4K |
image_model | string | Image generation model. 'nano_banana' (default) uses Google Gemini 3 Pro Image — faster and cheaper. 'gpt_image_2' uses OpenAI's GPT Image 2 — stronger on text rendering and brand consistency. enum: nano_banana, gpt_image_2 |
quality | string | Output quality. Only applies when image_model is 'gpt_image_2'. Defaults to 'medium' — ONLY pass 'high' when the user has explicitly asked for hero or final-quality output. For all drafts, iteration, and routine generations, omit this param and let the medium default apply ('high' + 4K is materially more expensive per image). Ignored for nano_banana. enum: low, medium, high, auto |
countrequired | integer | Number of images to generate in parallel (1-10, default 1). IMPORTANT: To generate multiple images, set this parameter instead of calling the tool multiple times. 1 – 10 · default: 1 |
webhook_url | string | Optional webhook URL to receive a POST request when the job completes. The payload includes job_id, status, asset_url, prompt, and other metadata. |
generate_video_clip
Generate a short video clip (4-8 seconds) using AI. Supports landscape (16:9) and portrait (9:16) formats. Optionally provide reference image URLs for style/character consistency. Returns a job_id immediately. The user will receive an email notification when the job completes. Use list_asset_jobs to check status and get the download URL.
Pricing: $0.3125/sec (fast) or $0.625/sec (full), with a $1.50 minimum per clip. Range $1.50–$5.00. Billed as max(150, ceil(duration × rate)).
| Parameter | Type | Description |
|---|---|---|
promptrequired | string | Detailed text prompt describing the video to generate. Use quotes for dialogue, describe sound effects explicitly. Max ~1024 tokens. |
aspect_ratiorequired | string | Aspect ratio: 16:9 (landscape) or 9:16 (portrait/vertical) enum: 16:9, 9:16 · default: "16:9" |
durationrequired | string | Video duration in seconds (4, 6, or 8) enum: 4, 6, 8 · default: "4" |
resolutionrequired | string | Video resolution. 4k is only available for 8s clips. enum: 720p, 1080p, 4k · default: "720p" |
qualityrequired | string | Quality tier: 'fast' ($1.50-$2.50, faster) or 'full' ($2.50-$5.00, highest quality) enum: fast, full · default: "fast" |
reference_image_urlsrequired | string[] | 0-3 reference image URLs for style/character consistency default: [] |
webhook_url | string | Optional webhook URL to receive a POST request when the job completes. The payload includes job_id, status, asset_url, prompt, and other metadata. |
enhance_promptrequired | boolean | When true (default), the prompt is automatically enhanced by an AI cinematographer before generation. Set to false for full manual control over the prompt. default: true |
tone | string | Creative tone/mood for the video. Examples: 'luxurious', 'playful', 'raw/authentic', 'cinematic', 'energetic', 'serene', 'bold' |
platform | string | Target platform — influences pacing, framing, and style conventions enum: instagram_reels, tiktok, youtube_preroll, youtube_shorts, other |
get_brand_guidelines
Look up canonical brand guidelines for your organization. Pass `domain` or `url` to fetch a specific record. With no arguments, returns the single brand on file if the org has exactly one; returns a `candidates` list to disambiguate if there are several; returns a friendly not-found message if there are none. All responses use a `{ found: true/false, ... }` envelope. Free.
| Parameter | Type | Description |
|---|---|---|
domain | string | Brand domain, e.g. 'beekman1802.com'. Optional — if omitted, the server resolves to the org's single extracted brand (or returns a candidate list to disambiguate). |
url | string | Any URL on the brand's site; domain is normalized from this. Optional — see `domain` for the no-args resolution behavior. |
list_asset_jobs
List recent asset generation jobs (images, videos, and landing pages). Returns job IDs, statuses, prompts, output URLs, and (for landing-page jobs) draft_id + content_hash you can pass to deploy_landing_page. Pass job_id to fetch a single job (useful for polling a specific generation). Use this to check on generation progress.
| Parameter | Type | Description |
|---|---|---|
job_id | string | Fetch a specific job by id. Use this when polling a generate_landing_page / generate_ad_asset / generate_video job you just kicked off — returns the same row shape as listing, just filtered to one. Other filters (limit/status/type) are ignored when set. |
limitrequired | integer | Number of recent jobs to return (1-100, default 20) 1 – 100 · default: 20 |
status | string | Filter by job status. Omit to return all statuses. enum: processing, completed, failed |
type | string | Filter by asset type. Omit to return all types. enum: image, video, video_edit, voice_replace, landing_page |
replace_voice
Replace a single spoken sentence in a video with new text, generated in a clone of the speaker's voice via ElevenLabs Instant Voice Clone. The matched span is replaced with TTS audio that's time-stretched to fit the original gap exactly, preserving total video duration. Useful for compliance edits to UGC ads (e.g. "tightened my neck" → "tightened the look of my neck"). Returns a job_id immediately; the user receives an email when the edit completes. Lip sync is NOT corrected — the visible mouth still reflects the original speech, which is fine for UGC with cuts and B-roll but visible on tight close-ups.
| Parameter | Type | Description |
|---|---|---|
video_urlrequired | string | HTTPS URL of the source video (MP4 with audio). Must contain the sentence in original_text on its audio track. |
original_textrequired | string | The exact sentence to locate and replace in the source. Matched against the transcript via the worker's tiered matcher (exact → fuzzy → LLM). |
replacement_textrequired | string | The new sentence to generate in the speaker's voice. Should be similar in length to the original — wildly different lengths (>4× or <0.25×) will be rejected by the worker as likely-wrong text. |
occurrence_index | integer | Which occurrence of original_text to target if it appears multiple times in the transcript. Defaults to 0 (first match). 0 – 9007199254740991 |
webhook_url | string | Optional webhook URL to receive a POST when the replacement completes. Same payload shape as generate_video_clip. |
search_inspiration_ads
Search a curated library of brand ads from Meta Ad Library for creative inspiration. Returns ad images ranked by visual similarity. Use the returned image URLs as inspiration_image_urls in generate_ad_asset to create ads inspired by a competitor's style.
| Parameter | Type | Description |
|---|---|---|
search_textrequired | string | Describe the kind of ad you're looking for (e.g. 'minimalist skincare ad with white background', 'bold fitness ad with athlete') |
brand_name | string | Filter to a specific brand (e.g. 'Clean Skin Club', 'Nike') |
category | string | Filter by industry category (e.g. 'Health/beauty', 'Apparel') |
platform | string | Filter by platform enum: FACEBOOK, INSTAGRAM |
active_onlyrequired | boolean | Only return currently active ads (default true) default: true |
limitrequired | integer | Number of results to return (1-50, default 10) 1 – 50 · default: 10 |
search_product_images
Search stored product images using multimodal embeddings (Gemini Embedding 2). Returns the most relevant product photos based on combined visual and textual similarity.
| Parameter | Type | Description |
|---|---|---|
search_textrequired | string | Describe the kind of product image you're looking for (e.g. 'blue athletic sneakers', 'luxury gold watch', 'summer beach accessories') |
limitrequired | integer | Number of results to return (1-50, default 5) 1 – 50 · default: 5 |
vectorize_product_images
Batch vectorize product images using multimodal AI (Gemini Embedding 2). Embeds both the raw image pixels and text description into a single vector — capturing visual and textual signals for high-quality search. Processing happens asynchronously. Results are searchable via search_product_images once complete.
| Parameter | Type | Description |
|---|---|---|
imagesrequired | object[] | Array of product images to vectorize (1-50) |
7. Pricing
Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.
| Tool | Cost |
|---|---|
| edit_video | 100¢ / call |
| extract_brand_guidelines | 300¢ / call |
| fetch_page | 10¢ / call |
| generate_ad_asset | 100¢ / result (min 100¢) |
| generate_video_clip | $1.50–$5 |
| get_brand_guidelines | Free |
| list_asset_jobs | Free |
| replace_voice | 150¢ / call |
| search_inspiration_ads | Free |
| search_product_images | Free |
| vectorize_product_images | 5¢ / result (min 5¢) |
8. Notes
- Most tools are organization-scoped — users only see their own catalog and jobs. Exception: `search_inspiration_ads` queries a shared library of 20k+ brand ads, available to all customers.
- Costs: `vectorize_product_images` 5¢/image, `fetch_page` 10¢/page, `generate_ad_asset` **$1/image**, `generate_video_clip` **~$1.50–$10/clip** depending on quality/duration/resolution, `extract_brand_guidelines` **$3/call** (one-time per brand; `get_brand_guidelines` is free thereafter). **Surface cost before batch generations, full-quality video, or brand extraction.**
- `generate_ad_asset`, `generate_video_clip`, and `extract_brand_guidelines` are async — pass `webhook_url` for a POST callback, otherwise watch for the email notification on completion.
- When the user passes inspiration images for ads, emphasize the AI copies *style* (layout, colors, typography, vibe) but creates original content — not a direct copy.
- Video prompt enhancement is on by default — simple descriptions work great, no need for the user to write sophisticated prompts.
- If a user asks to "create an ad" or "make a video" with no prior context, ask what product/brand and gather the needed image URLs before generating.