AdGen API — AI Ad Campaign Generation API

Brief in → ad copy, branded images and a rendered campaign video out. One REST API, English and Arabic, with a free tier and an instant API key.

Base URL: https://adgen-api.sikasio.com

You describe the brand and the goal. AdGen plans the campaign — a headline, body, caption, hashtags and an image prompt per post — then generates the branded images and renders them into a short vertical ad video with an AI-written script and optional narration. Copy, images, narration and pacing are produced by AdGen AI. Planning is synchronous; images and video renders are jobs you poll.

Quick facts

Base URL

https://adgen-api.sikasio.com

Flow

POST /v1/campaigns → …/images → …/video → poll GET /v1/jobs/:id

Auth

X-API-Key header — instant free key at /signup

Image models

flash · studio · vivid

Voices

aria · nova · sami · omar · mixed (EN + Arabic)

Output

JSON campaign plan, hosted image URLs, MP4 video + thumbnail on the AdGen CDN

Credits

campaign plan 2 · image 2 · hook options free · video 12 (basic) / 20 (creative)

Pricing

Free $0 (40 credits/mo) · Starter $19/mo (400) · Pro $49/mo (1,200)

Provider

Sikasio · support@sikasio.com

Get your free API key →

Getting your API key

New here? You can be making your first request in under a minute:

1. Create a free account at /signup — name, email and a password, and accept the terms. No card required.
2. Verify your email by entering the 6-digit code we send you.
3. Copy your API key — it's shown once, right after verification, so save it somewhere safe. You can regenerate a fresh key any time from your dashboard.
4. Send the key as the X-API-Key header (or Authorization: Bearer) on every /v1 request.
5. Make your first call: POST /v1/campaigns with a brief — see the quick start below.

Already have an account? Sign in. Forgot your password? Reset it here.

Authentication

Every /v1 request must carry your API key, either way:

X-API-Key: adg_live_YOUR_KEY
Authorization: Bearer adg_live_YOUR_KEY

A missing or unknown key returns 401 {"error":"Invalid API key"}. Keys are scoped to their own data: a campaign or job belonging to another key returns 404, never 403.

GET /healthz is the one endpoint that needs no API key — and it costs no credits. Everything else under /v1 requires a key. Request bodies are capped at 1 MB, and every response body is JSON.

CORS: enabled (Access-Control-Allow-Origin: *) — auth is a header, not a cookie, so you can call the API and embed the returned asset URLs directly from browser apps.

Plans & pricing

Every plan sets a monthly credit allowance, a requests-per-minute ceiling, and how long finished assets stay hosted:

Paid plans are billed monthly. Allowances reset at the first instant of each UTC calendar month (resets_at on GET /v1/account) and unused credits do not roll over. Upgrade or cancel any time from your dashboard.

Finished assets are served from stable URLs on the AdGen CDN and may be removed after the retention window for your plan — download anything you need to keep.

Credits

Charged on success. A campaign plan is reserved when the request starts and refunded in full if copy generation fails (a failed plan creates no campaign and costs nothing). An image batch reserves 2 × selected posts and refunds every image that fails; if none succeeds, the whole batch is refunded. A video render is priced and checked when it is queued — so you get a 402 immediately if you cannot afford it — and charged only when it finishes done. A failed or cancelled render costs nothing.

402 {"error":"Insufficient credits","required":12,"remaining":4}

Quick start

1. Plan the campaign

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns" \
  -H "X-API-Key: adg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": { "name": "Acme Coffee", "colors": ["#1e293b"] },
    "goal": "Launch our cold brew subscription",
    "audience": "office workers in Cairo",
    "tone": "friendly, confident",
    "cta": "Start your subscription",
    "language": "en",
    "postCount": 4
  }'

{ "id": "9f3c1a77b2e40d51", "status": "ready",
  "posts": [ { "id": 1, "order": 0, "headline": "…", "body": "…", "caption": "…",
               "hashtags": ["…"], "imagePrompt": "…", "imageStatus": "planned", "imageUrl": null } ] }

2. Generate the images

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns/9f3c1a77b2e40d51/images" \
  -H "X-API-Key: adg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "studio" }'

{ "jobId": "4a7d2f0e91bc38da" }

Poll the job at your plan's cadence until it's done, then read the image URLs back from GET /v1/campaigns/9f3c1a77b2e40d51.

3. Pick an opening hook (free)

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns/9f3c1a77b2e40d51/hooks" \
  -H "X-API-Key: adg_live_YOUR_KEY" -H "Content-Type: application/json" -d '{}'

{ "options": [ { "style": "question", "lang": "en",
                 "headline": "Ready for\nthe next level?", "underline": "next level",
                 "kicker": "Acme Coffee" } ], "cached": false }

4. Render the video

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns/9f3c1a77b2e40d51/video" \
  -H "X-API-Key: adg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "creative",
    "aspect": "portrait",
    "hook": { "headline": "Ready for\nthe next level?", "underline": "next level" },
    "voiceover": { "enabled": true, "voice": "aria" }
  }'

{ "jobId": "1c9be05af7d2461a" }

5. Poll the job

curl "https://adgen-api.sikasio.com/v1/jobs/1c9be05af7d2461a" \
  -H "X-API-Key: adg_live_YOUR_KEY"

{ "id": "1c9be05af7d2461a", "status": "done", "progress": 100,
  "videoUrl": "https://adgen-cdn.sikasio.com/…mp4",
  "thumbnailUrl": "https://adgen-cdn.sikasio.com/…jpg" }

Jobs & polling

Image batches and video renders are asynchronous: they answer 202 {"jobId":"…"} and you poll GET /v1/jobs/:id.

Finished assets (videoUrl, thumbnailUrl and each post's imageUrl) are stable URLs served from the AdGen CDN.

Rather than polling a video render to the end, you can have AdGen POST a signed event to your server when it finishes — see webhooks. Polling still works, and remains the authority: webhook delivery is best-effort.

Polling cadence

Every poll spends from your plan's rate limit, so pick an interval your ceiling can sustain for the whole job:

Nothing is lost by polling slowly: a video render takes a few minutes and an image batch runs about 30–60 seconds per image, so a 15-second interval still reports a finished job within a few percent of its total runtime. Leave headroom — the ceiling covers all /v1 calls, so a loop that also reads GET /v1/campaigns/:id between polls needs a slower interval than the table.

If you do get a 429, wait the number of seconds in the Retry-After header and carry on — a rate-limited poll never affects the job, which keeps running.

Create a campaign

Turns a brief into a campaign with planned posts. Synchronous — the response carries the finished posts and typically takes 5–20 seconds (it scales with postCount), so set your client timeout to at least 60s. A failure means no campaign was created and no credits were spent.

Returns 201:

{
  "id": "9f3c1a77b2e40d51",
  "status": "ready",
  "artDirection": "…",
  "posts": [
    { "id": 1, "order": 0, "headline": "…", "body": "…", "caption": "…",
      "hashtags": ["…"], "imagePrompt": "…", "imageStatus": "planned", "imageUrl": null }
  ]
}

artDirection appears only when consistentIdentity was requested and an art direction was produced. imageStatus is one of planned · generating · done · failed.

Errors: 400 validation ({"error":"brand.name is required"}), 402 insufficient credits, 502 {"error":"Copy generation failed. Please retry."} — nothing charged, safe to retry.

Read a campaign

Reads a campaign back, including the current image state of every post — this is where finished image URLs appear after an image batch completes.

{
  "id": "9f3c1a77b2e40d51",
  "status": "ready",
  "artDirection": "…",
  "brief": { "brand": { "name": "Acme", "colors": ["#1e293b"], "logoUrl": null },
             "goal": "…", "audience": "…", "tone": "…", "cta": "…",
             "language": "en", "market": "global", "style": "realistic", "aspect": "portrait" },
  "posts": [ { "id": 1, "order": 0, "imageStatus": "done",
               "imageUrl": "https://adgen-cdn.sikasio.com/…", "…": "…" } ]
}

artDirection and brief.cta are present only when they were set; posts[] has the same shape as in the create response. An unknown id — or one owned by another key — is 404 {"error":"Campaign not found"}.

Opening-hook options

Scroll-stopping opening-hook options for the campaign's video, written from its own copy in the market's language. Costs 0 credits (but still needs your API key, like every /v1 endpoint), and cached for 24 hours per market.

{ "options": [ { "style": "question", "lang": "en",
                 "headline": "Ready for\nthe next level?",
                 "underline": "next level", "kicker": "Acme" } ],
  "cached": false }

Ten options come back in the normal case — two variants each of five archetypes: question, bold, pain, stat, curiosity. headline may contain a single \n (a two-line hook); underline and kicker are optional. Any usable set of 4 or more options is cached for 24h, so a short set can be served with cached: true for the rest of the day — pass force: true to regenerate. If copy generation fails outright, a 2-option built-in set is returned and is not cached, so the next call retries.

Pass a chosen option straight into POST /v1/campaigns/:id/video as hook: { headline, underline?, kicker? }.

Generate campaign images

Queues image generation for the campaign's posts. Returns immediately; poll the job, then read the URLs from GET /v1/campaigns/:id.

202 { "jobId": "4a7d2f0e91bc38da" }

Credits: 2 × selected posts, reserved now and refunded per failed image. Images are generated one after another — expect roughly 30–60 seconds per image, so a 4-post batch runs 2–4 minutes. Per-post progress shows up as the job's stage ("image 2/4"). Partial success is a done job: the posts that landed have imageStatus: "done" with a CDN imageUrl, the rest are failed and refunded.

One batch per campaign at a time. While a campaign's batch is queued or rendering, a second request for the same campaign is refused with 409 and nothing is charged — poll the job, then retry. A batch that ended done, failed or cancelled never blocks a retry.

Re-generating an image is allowed at any time — pass the postIds you want redone, or send no postIds to redo everything not yet done (a post whose last attempt failed is included, so a plain retry needs no hand-picked ids). If a retry fails, the image you already had is kept: the post reads imageStatus: "failed" while imageUrl still points at the last image that succeeded, so a failed retry never costs you a working asset. A post that never had one keeps imageUrl: null. A successful retry replaces the URL.

Errors: 400 unknown model, bad referenceImageUrl, {"error":"postIds must be an array of integers"}, {"error":"Unknown postId 7"}, {"error":"No posts selected — every post already has an image"}; 402 insufficient credits; 404 unknown campaign; 409 {"error":"An image batch is already running for this campaign"}.

Use your own images

Attaches images you already have to the campaign's posts — from your own pipeline, a designer, or an earlier campaign. Free (no model runs), and it makes the campaign renderable without buying images here: POST /v1/campaigns/:id/video reads exactly these URLs.

PUT /v1/campaigns/4a7d.../images
{ "images": [ { "order": 0, "url": "https://cdn.example.com/a.png" },
              { "order": 1, "url": "https://cdn.example.com/b.png" } ] }

200 { "posts": [ { "id": 1, "order": 0, "imageStatus": "done", "imageUrl": "https://cdn.example.com/a.png", ... } ] }

Only the posts you list change; the rest keep whatever they had. Attaching over an existing image replaces it. The whole request is all-or-nothing — one bad entry rejects the request and writes nothing, so a campaign is never left half-updated.

Errors: 400 {"error":"images must be a non-empty array"}, {"error":"Every images entry needs exactly one of postId or order"}, {"error":"Unknown postId 7"}, {"error":"Every images entry needs a public http(s) url"}; 404 unknown campaign; 409 {"error":"An image batch is already running for this campaign"} — a running batch owns these posts, so wait for it to finish.

Render the campaign video

Renders the campaign into a short vertical ad video: the generated post images become the visuals, AdGen AI writes the script, picks the color system and (when enabled) the narration pace. Requires at least one post with a generated image — up to 6 are used, in order.

The voiceover object

Arabic narration is Modern Standard Arabic (فصحى), delivered with the selected market's accent and cultural register.

202 { "jobId": "1c9be05af7d2461a" }

Credits: 12 (basic) / 20 (creative), charged when the job reaches done.

Errors: 400 {"error":"Campaign has no generated images yet"}, 400 unknown market, 402 insufficient credits, 404 unknown campaign.

Render a video directly

Render a video from raw scenes and/or a script without a stored campaign — you supply the images and copy. Same engine, same job semantics and same prices.

You must provide scenes[], script[], or both.

script[] entries

An unknown type is a 400 (never silently dropped), and any imageUrl must be a public http(s) URL.

202 { "jobId": "1c9be05af7d2461a" }

Errors: 400 {"error":"brand.name is required"}, 400 {"error":"Provide scenes[] or script[]"}, 400 {"error":"mode 'creative' requires script[]"}, 400 {"error":"Every scene needs a public http(s) imageUrl"}, 400 {"error":"Unknown scene type '…'"}, 402 insufficient credits.

Retrieve a job

{
  "id": "1c9be05af7d2461a",
  "status": "rendering",
  "progress": 62,
  "stage": "encoding",
  "videoUrl": null,
  "thumbnailUrl": null,
  "error": null,
  "createdAt": 1785000000000,
  "finishedAt": null
}

createdAt / finishedAt are epoch milliseconds. videoUrl and thumbnailUrl are CDN URLs, filled in when status is done. For image batches the job carries progress only — the images themselves are read from GET /v1/campaigns/:id. An unknown id, or one owned by another key, is 404 {"error":"Job not found"}.

A video render typically takes a few minutes: choose your interval from the polling cadence table and honor Retry-After on a 429.

Cancel a job

Cancel a job — before it starts or mid-render.

200 {"status":"cancelled"}   // stopped immediately (was still queued)
200 {"status":"cancelling"}  // in progress; stops at its next checkpoint

409 {"error":"Job already finished"} if it already reached a terminal status; 404 for an unknown id. Cancelled work is refunded — image batches per undelivered image, and a cancelled render was never charged.

Check your account

Your plan, this month's spend, and the live price list.

{
  "name": "acme-production",
  "plan": "starter",
  "monthly_credits": 400,
  "used_this_month": 6,
  "remaining": 394,
  "reserved": 12,
  "available": 382,
  "resets_at": "2026-08-01T00:00:00.000Z",
  "costs": { "plan": 2, "image": 2, "hooks": 0, "video_basic": 12, "video_creative": 20 }
}

used_this_month is the net spend for the current UTC month (refunds subtracted), and remaining is the allowance minus that spend — neither counts the credits held by renders still in flight. reserved is the total held by outstanding renders, and available is the allowance after spend and holds: the figure every affordability check uses, so it is what you can actually queue right now (see credits). resets_at is the first instant of the next UTC month.

Health check

No key, no credits — 200 {"ok":true} while the service is up. Live component status is on the status page.

Webhooks

Instead of polling — or alongside it — AdGen POSTs a signed JSON event to your server the moment a job reaches a terminal state. Configure one endpoint in your dashboard: paste an https:// URL, save, and copy the signing secret, which is shown once.

Scope: video renders only. job.completed and job.failed are emitted for video render jobs (POST /v1/campaigns/:id/video and POST /v1/videos). An image batch emits nothing today — poll its job and read the finished images from GET /v1/campaigns/:id.

The endpoint belongs to your account, not to a key: regenerating your API key does not affect it, and events for jobs queued under an older key keep arriving. The URL must be public — loopback, private, link-local, CGNAT and multicast targets are refused when you save them and again at delivery time.

The request

POST /hooks/adgen HTTP/1.1
Host: your-app.example.com
Content-Type: application/json
X-AdGen-Signature: t=<unix-seconds>,v1=<hex>
X-AdGen-Delivery-Id: 4711

{
  "event": "job.completed",
  "jobId": "1c9be05af7d2461a",
  "campaignId": "9f3c1a77b2e40d51",
  "status": "done",
  "videoUrl": "https://cdn.example/v.mp4",
  "thumbnailUrl": "https://cdn.example/t.jpg",
  "error": null,
  "creditsCharged": 12,
  "createdAt": 1785000000000,
  "finishedAt": 1785000060000
}

All ten keys are always present (null means "does not apply"), and new keys may be added later, so ignore ones you do not recognize. status, videoUrl, thumbnailUrl, error, createdAt and finishedAt carry exactly the values GET /v1/jobs/:id returns for the same job, in the same epoch-millisecond units — poll and listen at once and you can never see two different answers for them — and the webhook's jobId is that endpoint's id. Three fields are webhook-only: event, campaignId and creditsCharged; that last one has no counterpart when you reconcile by polling, so record it when the event arrives if you need per-render billing. creditsCharged is what you were actually billed, net of refunds and 0 for failed or cancelled renders. A cancellation is a job.failed with "status":"cancelled" — it produced no video, so it belongs in your failure branch.

X-AdGen-Delivery-Id is the idempotency key: one delivery has one id, and it is stable across every retry. Dedupe on it.

Verifying the signature

X-AdGen-Signature is t=<unix-seconds>,v1=<hex>, where v1 is HMAC-SHA256 over ${timestamp}.${body} with your secret, in lowercase hex. The timestamp is inside the signed bytes, which is what makes a captured request expire rather than replay forever. body must be the raw request bytes: re-serializing a parsed object changes key order and spacing, and the signature will not match. Allow 300 seconds of clock skew and reject anything outside it.

app.post('/hooks/adgen', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8')
  const [t, v1] = req.get('X-AdGen-Signature').split(',').map((p) => p.slice(p.indexOf('=') + 1))
  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${raw}`).digest('hex')
  if (expected.length !== v1.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
    return res.sendStatus(400)
  }
  res.sendStatus(200)          // answer FIRST, do the work after
  queueForProcessing(JSON.parse(raw))
})

That snippet is the minimum. Two more rules are worth adding: reject a signature whose t falls outside your tolerance window (that is what makes a captured request expire), and reject a header carrying a repeated field — an attacker who can append ,v1=… must not get to choose which of two signatures you check.

Responses, retries and give-up

Answer 2xx as soon as you have stored the event and do the work afterwards: a handler that renders something of its own before replying will hit the timeout and be retried. Four cases are retired without retrying, because no later attempt could succeed: a URL that is not a public http(s) address; a hostname that resolves to a private address (refused at connect time on the first attempt — including a split-horizon name that answers with both a public and a private record, since every address returned has to pass); a webhook removed while the delivery was queued; and a webhook repointed to a different URL, whose already-queued deliveries are retired rather than sent to an endpoint you have disowned.

You can rotate the signing secret without touching the URL at any time. Queued deliveries keep flowing, because each attempt signs with the current secret — accept both the old and the new one while you deploy the change.

What is guaranteed

At most once at the source. An event fires only on a job's real terminal transition, so a duplicate or late finish never fires a second one — but queuing it is deliberately best-effort (webhook bookkeeping must never fail a render that already succeeded), so a crash between the status write and the queue insert drops the event permanently. At-least-once in delivery: a retry can send the same event twice, so dedupe on X-AdGen-Delivery-Id. GET /v1/jobs/:id is the authority — if you must never miss a terminal state, sweep your outstanding job ids on a slow timer and read them back.

Cancellation is asymmetric: DELETE /v1/jobs/:id answering {"status":"cancelled"} is terminal and sends no webhook — that response is the notification — while {"status":"cancelling"} means a worker still holds the job and a job.failed with "status":"cancelled" follows when it stops.

Markets

market adapts copy, hooks and narration to a market's language, customs and way of speaking. auto (or omitting the field) picks eg for Arabic campaigns and global for English ones. Arabic markets are written in Modern Standard Arabic with the market's own register.

Styles

style sets the shared visual language of a campaign's images.

Errors

Every response body is JSON carrying a single error string, plus required/remaining on a 402.

Two of these are raised before your request reaches an endpoint — a body that is not valid JSON is 400 {"error":"Invalid JSON body"} and one over the size cap is a 413 — so they are answered before the API key is even checked.

Rate limits

Each key gets a requests-per-minute ceiling from its plan, counted over all /v1 endpoints together (cheap reads included). Over the ceiling is 429 {"error":"Rate limited"} with Retry-After: 60. The window is a fixed clock minute, so a 429 clears at the next minute boundary — wait out Retry-After and retry; nothing is charged and no job is affected.

A separate ceiling applies per source IP address across every endpoint, answering with 429 {"error":"Too many requests"} — normal use never reaches it.

Polling a job is the one loop that can realistically reach the ceiling; see polling cadence for the interval to use on each plan.

FAQ

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns" \
  -H "X-API-Key: adg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":{"name":"Acme Coffee"},"goal":"Launch our cold brew subscription","postCount":4}'

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns/CAMPAIGN_ID/images" \
  -H "X-API-Key: adg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"studio"}'

curl -X POST "https://adgen-api.sikasio.com/v1/campaigns/CAMPAIGN_ID/video" \
  -H "X-API-Key: adg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"creative","voiceover":{"enabled":true,"voice":"aria"}}'

Get an API key

Sign up and get a free key instantly — 40 credits a month, no card required. Upgrade to starter or pro from your dashboard whenever you need more.

Get your free API key →

Questions? support@sikasio.com