API Reference

Documentation

Adsmithy API

Generate professional ads with AI — optimized for Google, Amazon, Meta, TikTok and 15+ platforms. Integrate Adsmithy into your workflows via REST API.

AI Generation

15+ models

20 Platforms

Google, Meta, Amazon…

API Key Auth

Bearer token

Rate Limits

Per plan

Base URL

https://adsmithy.com/api/v1

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. Create and manage your keys in Settings → API and AI assistants.

Key format

ask_live_[48 hex chars]

Required plan

ProAgency

Keep your API key secret. Never expose it client-side in public code or commit it to version control. Use environment variables.

AI assistants (MCP)

Adsmithy is also an MCP server: Claude Code, Cursor and other AI assistants can make, list and critique your ads themselves. Same key, scopes, rate limits and credits as the API; every ad lands in your Library.

claude.ai, ChatGPT and other assistants with connectors

Add a custom connector with the address https://adsmithy.com/api/mcp, then sign in to your Adsmithy account and allow access. No key to copy: the assistant signs in with OAuth (Pro and Business plans).

Claude Code (with an API key)

Cursor and other clients

A remote MCP server (Streamable HTTP) at https://adsmithy.com/api/mcp, with your key in the Authorization header.

Tool	What it does	Credits
generate_ad	One ad (POST /generate)	The model's cost
generate_ads	Variations for several platforms (POST /generate/batch)	Per image made
score_ad	AI critique of ads (POST /score)	1 per ad
list_generations	Your ads (GET /generations)	Free
get_generation	One ad, with a preview (GET /generations/:id)	Free
list_models	Models, costs and platform presets (GET /models)	Free
get_account	Plan and credits left (GET /me)	Free

Rate Limits

Limits are applied per API key using a sliding window. Rate limit headers are included in every response.

Plan	Requests / hour	API Access
Free	—
Starter	—
Pro	100 req/h
Agency	500 req/h

Platform Presets

Pass a platform field to POST /generate to automatically apply the correct aspect ratio and style guidance.

google_display

Google Display

16:9

google_responsive

Google Responsive

1:1

amazon_product

Amazon Product

1:1

amazon_lifestyle

Amazon Lifestyle

16:9

meta_feed

Meta Feed

4:5

meta_story

Meta Story

9:16

meta_carousel

Meta Carousel

1:1

tiktok

TikTok

9:16

linkedin_post

LinkedIn Post

1.91:1

youtube_thumbnail

YouTube Thumbnail

16:9

pinterest_pin

Pinterest Pin

2:3

snapchat_story

Snapchat Story

9:16

GET/api/v1/me

Returns the authenticated user's account info: plan, credits balance, rate limits, and active scopes.

Response

Example

GET/api/v1/models

List all available AI generation models with their capabilities, supported aspect ratios, and credit costs.

Response (excerpt)

Example

POST/api/v1/generate

Generate a single ad image. Optionally target a specific platform to automatically apply the correct dimensions and style guidance. Credits are consumed on success.

Request Body

promptrequired

string

The generation prompt describing the ad.

platform

string

Platform preset ID (see Platform Presets). Overrides aspect_ratio.

model

string

AI model to use. Default: "nano-banana-2.1", the model the app uses. See GET /models.

aspect_ratio

string

Aspect ratio override. One of: "1:1", "16:9", "9:16", "4:5", "4:3", "2:3"...

reference_images

string[]

Array of image URLs to use as style/content reference (max 4, model-dependent).

brand_id

string

Your brand ID. Automatically injects brand name and colors into the prompt.

product_id

string

Scraped product ID. Injects product name and description.

platform_params

object

Ad-specific context: { headline, description, cta, target_audience, tone }. Tone: "professional" | "playful" | "luxury" | "bold" | "minimalist".

output_format

string

"webp" (default) | "jpg" | "png"

Response

Example

POST/api/v1/generate/batch

Generate multiple ad variations across one or more platforms in a single call. Total images = count × platforms.length. Credits are consumed only for successful generations.

Request Body

promptrequired

string

Base prompt. Each variation explores a different composition.

count

number

Number of variations per platform. Min 1, max 10. Default: 3.

platformsrequired

string[]

Array of platform preset IDs. Min 1, max 5. Default: ['meta_feed'].

model

string

AI model to use. Default: "nano-banana-2.1", the model the app uses.

brand_id

string

Brand ID for context.

platform_params

object

Shared ad params: { headline, cta, tone }.

Response

Example

POST/api/v1/score

Score one or more ads using AI vision analysis. Returns an overall score (0-100), component breakdown, CTR/CVR predictions, and improvement recommendations. Cost: 1 credit per ad.

Request Body (one of)

generation_id

string

Score by generation ID (recommended — no extra credit needed for image fetch).

generation_ids

string[]

Batch score up to 20 generation IDs at once.

image_url

string

Score any image by URL.

context

string

Optional prompt/context to improve score accuracy (used with image_url).

Response

Example

GET/api/v1/generations

List your ad generations with pagination. Filter by status or brand.

Query Parameters

limit

number

Results per page. Max 100, default 20.

offset

number

Pagination offset. Default 0.

status

string

"pending" | "completed" | "failed"

brand_id

string

Filter by brand ID.

Response

Example

GET/api/v1/generations/:id

Get full details of a specific generation including AI scores, recommendations, and batch info.

Response

Try it

Use a real generation_id from .

Error Codes

All errors return a JSON body with error and code fields.

HTTP	Code	Description
401	`MISSING_AUTH`	Missing or invalid Authorization header.
401	`INVALID_KEY`	API key not found.
401	`KEY_REVOKED`	API key has been revoked.
401	`KEY_EXPIRED`	API key has expired.
402	`INSUFFICIENT_CREDITS`	Not enough credits to complete the request.
403	`PLAN_UPGRADE_REQUIRED`	API access requires Pro or Agency plan.
403	`INSUFFICIENT_SCOPE`	API key missing required scope.
429	`RATE_LIMIT_EXCEEDED`	Hourly rate limit exceeded.
500	`GENERATION_FAILED`	AI generation failed. Retry the request.