CreaScale AI API

Easiest mode: the public URL of ONE product page. CreaScale reads the page (photos, name, price, description), plans a different marketing angle for each image (persona × desire × awareness), writes the headline (French, English or Arabic) and composes the scene. Nothing else is required.

Optional, with product_url: your own idea in your words (≤ 500 chars), e.g. "focus on the gift for Mother's Day". Every concept follows it.

Scene / creative direction (≤ 2000 chars): setting, light, people, props. Put the ad text in headline / subline / cta, not here. Required unless product_url, headline, subline, products or ads is given.

Exact headline written on the image (≤ 120 chars).

Exact small line (offer, price, format…), ≤ 200 chars.

Up to 2 more exact small lines (e.g. "Cash on delivery").

Optional call to action (≤ 40 chars). Without it, no button, pill or badge is drawn.

ISO code of the text on the image ("fr", "en", "ar"…). Default: detected from the headline.

"exact" (default when headline / subline / cta is given: these lines and nothing else), "none" (no text at all) or "auto" (CreaScale writes one headline in `language`).

Up to 4 real products: { name, image_urls (≤ 4 public photo URLs), label_lock (the exact label text, one string per printed line), quantity }. Exactly these products appear — no invented extra one.

"generate" (default: the model redraws the product from the photos) or "composite" (your real product photo is cut out and placed in the generated scene — pixel-exact label; for packshots and still lifes, not for hands holding the product).

"4:5" (default), "1:1", "9:16", "3:4", "2:3" or "16:9".

Minimum height of the tallest product, as a fraction of the image height (default 0.4 when products are given).

Default false: no alcohol or tobacco in the picture.

Variations of this spec (default 1). Camera angle and light vary; text and products never do. With product_url: the number of different angles.

"draft" (3 cr), "standard" (5 cr, default) or "premium" (9 cr, 2K). Premium is Pro+ — clamped to standard on lower plans.

Batch: up to 50 different specs (each with its own prompt / headline / products…). Top-level fields act as defaults.

Legacy: up to 4 public photo URLs when you cannot split them per product. Prefer products.

Optional. Up to 4 base64 data URLs (data:image/...;base64,...), ≤ 3 MB each — used as product references.

What to advertise (≥ 10 chars after enrichment, ≤ 1000). Optional only if product_url is given and scrapable.

Landing page to scrape (SSRF-hardened). Its text enriches the brief verbatim and its product images become visual references.

Distinct variants in one call (default 1). Clamped to your plan cap: Free 1 / Starter (existing subscribers) 2 / Pro 20 / Scale 50 / Enterprise 100. Clamped, never rejected.

"draft" (30 cr), "standard" (50 cr, default) or "premium" (90 cr) — at the 16s reference.

8 to 120 seconds (default 16). Starter (existing subscribers) is capped at 16s server-side.

ISO country used for cultural framing (e.g. "MA").

Spoken language (e.g. "ar-MSA", "fr", "en").

"male" or "female". Anything else falls back to automatic selection.

Up to 4 base64 data URLs (data:image/...;base64,...), ≤ 3 MB each.

Returns the generated scene plan with a 200 and debits NOTHING. Use it to preview a brief before spending credits.

Prompt shorter than 10 characters after enrichment, or product_url that failed URL validation.

Insufficient credits — carries credits_required. Any project already created is rolled back, so a partial batch is never billed.

Monthly video cap reached (Starter (existing subscribers) 2/month, Pro 12/month; Scale and Enterprise are bounded by credits only). The message states the cap and the count already used.

Max 10 creations per minute per API key.

Provider temporarily unavailable (fal_locked: true). NOTHING is debited — retry in a few minutes.

Landing page URL to analyze (HTTPS recommended)

Product/service description (helps Claude generate better angles)

Market niche (e.g., skincare, SaaS, fitness)

Target country code (e.g., US, FR, MA)

Output language (e.g., en, fr, ar)

Brand voice (e.g., professional, playful, luxurious)

Run name for your reference

Optional. Up to 5 public image URLs (jpeg/png/webp/gif, ≤15MB each). Used as visual references for image generation. SSRF-protected.

Optional. Up to 5 base64-encoded images: { file_name?, mime_type, data }. Combined with product_image_urls, total ≤ 5. MIME + magic bytes validated.

Results per page (default: 20, max: 100)

Pagination offset (default: 0)

Filter by status: pending, running, completed, failed

Your number is connected via the Agent tab (official Meta Cloud API). No number = 409 no_whatsapp_channel.

Templates are created and approved in Meta Business Manager (a payment method must be attached to your WABA — Meta refuses all templates without one).

templates_enabled is on for your workspace. Off = 409 templates_disabled on every send.

CreaScale never bills template messages — Meta charges your WhatsApp Business Account directly.

Customer phone in international digits (E.164 without +).

Template name, exactly as approved in Meta.

Template language code (fr, ar, en, …) — must match an approved variant.

Flat array of body variables, in {{1}}, {{2}}, … order.

Header variables, if the template has a text header.

Dynamic URL suffix, if the template has a dynamic-URL button.

Payloads for quick-reply buttons (e.g. "CONFIRM:8832"). Echoed back verbatim in message.received when the customer taps.

Utility template sent when a Shopify order is created.

Free-text confirmation for the non-official rail. Max 1024 chars.

Template sent when the order becomes fulfilled.

Generic follow-up after the customer replies (24h window). Max 1024.

Follow-up when the customer tapped the confirm button.

Follow-up when the customer tapped the cancel button.

Watch a Google Sheet — a new row triggers a send. Opt-in: false clears it.

Google Sheet link shared for reading. Only docs.google.com is accepted; any other host is refused.

Template sent to new Sheet rows.

Column mapping { phone_idx, var_idx[≤3], header }. You supply it — the API does not guess. Without it the sweep falls back to a heuristic and may read the wrong columns.

A key outside the list above. The offending names come back in fields[]. Nothing is written — a setting silently ignored would leave you believing your order confirmation was armed while nothing goes out.

A value the validator refused (a Sheet URL outside docs.google.com, a text over its limit). The rejected keys are named in fields[], and every OTHER key in the same request is left untouched.

The body contained no writable key.

Customer phone (E.164, with or without +) or Instagram IGSID. The most recent conversation with that customer on the channel is used.

Alternative to to: target one thread precisely (from GET /conversations or the message.received webhook).

Up to 900 characters.

"whatsapp" (default) or "instagram". Only with to.

This customer never wrote to you on that channel: there is no window to use. Send a template, or wait for their message.

More than 24 h since the customer's last message. meta_error carries Meta's text verbatim.

Texts count against your plan's monthly cap (Pro 10,000 · Scale 100,000 · Enterprise unlimited), cockpit and API combined. No credits are debited. Response carries cap and used. free_cap_reached is never returned here: a Free account is refused upstream with plan_required — that reason exists only on POST /messages/template.

Any other Meta refusal (expired token, blocked account…) with meta_error and meta_code. Nothing was sent.

30 texts per minute per key, under the global 60 req/min.

Customer phone (E.164, with or without +). Alternative: conversation_id, to target one thread precisely.

"image" · "video" · "document" · "audio".

Publicly reachable HTTPS URL, up to 2048 characters. We fetch it once, at call time. HTTPS is required on the whole path: a redirect that leaves HTTPS is refused — your file is often a customer's voice note, and cleartext makes it both readable and substitutable in transit.

Image and video only, up to 900 characters. Meta's limitation, not ours.

Document only, and required there — without it your customer sees a truncated URL.

Audio only. true = delivered as a WhatsApp voice note (plays inline, waveform, auto-download) instead of an audio file to download. Meta requires an Ogg file encoded with OPUS, mono; the play button only shows at 512 KB or less. false or omitted = audio file, as before. Since we upload, we also check the container before sending: bytes that are not Ogg/OPUS mono return 400 media_voice_format_invalid, rather than letting Meta accept them and silently degrade the message.

caption: yes · filename: no

caption: yes · filename: no

caption: no · filename: no · voice: yes (Ogg/OPUS mono)

caption: no · filename: required

Reading your link + uploading to Meta. Past it: 504 media_timeout.

Handing the message to Meta, with bounded retries.

Set your client timeout to 90 s at least. 20 s suited the old rail and no longer does.

Our id for this send. GET /messages/{id} accepts it, and message.* acknowledgements carry it.

The Meta wamid — the key every delivery acknowledgement quotes.

The media object id at Meta, kept 30 days. Verifiable with your own WABA token: GET /v21.0/{media_id} returns mime_type, file_size and sha256. null when the media went out by link.

"uploaded" in the nominal case. "link" only above 16 MB — which can only happen with a document: the upload does not fit in one synchronous request, so the media goes out by link as before and its copy at Meta becomes perishable again. Assert this field if your customers must be able to reopen the file hours later.

URL we refuse to fetch: scheme, private IP, cloud metadata endpoint, too many redirects, or a redirect that leaves HTTPS. Permanent — fix the URL, do not replay.

Beyond Meta's size limit for that type. detail carries the size we read. Permanent.

voice: true on bytes that are not Ogg/OPUS mono. Permanent.

Your host did not answer, or did not answer 2xx, within 12 s. Replayable.

Meta refused the upload. meta_error and meta_code are Meta's own. Replayable.

Preparation went past its 20 s ceiling. Replayable — with the SAME Idempotency-Key.

Too many media bytes already being read on our server. We hold your bytes in memory while uploading them, so we cap it — a named refusal beats a saturated server. Replayable in a few seconds.

Not HTTPS, unparseable, or over 2048 characters.

Caption on an audio or a document. Meta's rule — refused here rather than as an opaque (#100) from Graph.

A document without a filename reaches your customer as a truncated URL.

voice is not a boolean. It is never silently ignored.

voice: true on a type other than audio.

Instagram is not served: no document, no audio, no caption there.

More than 24 h since the customer's last message. Media is a service message, exactly like free text. Send a template.

Media counts against the same monthly cap as text, cockpit and API combined. No free_cap_reached on this rail either — see POST /messages/template.

Meta no longer serves this media: webhook media ids expire after 7 days.

Above Meta's limit for that type. Refused before downloading.

Meta refused the send right away. Its error is returned verbatim.

Meta accepted the link (200) and refused the file when it fetched it: link unreachable, wrong type or encoding, too large. Arrives as a message.failed event with error_code (typically 131053) and error_details.

30 media sends and 60 downloads per minute per key.

Connections and attached accounts (labels, Page, pixel, Instagram, readiness and blockers, last sync).

Connect a pasted token { access_token, label? }. Meta validates it first (GET /me). 201 new connection, 200 same Meta user reconnected (token replaced). One ad account + one Page visible = attached automatically.

Businesses, ad accounts, Pages, pixels this token sees now, plus the ad accounts already attached.

Remove the connection and its accounts; the token is purged from the vault.

Attach an account { login_id, ad_account_id, page_id, pixel_id?, instagram_id?, business_id?, label? }. Every id is re-checked against the token's inventory (409 account_already_attached, max_accounts_reached).

Change page_id, pixel_id, instagram_id, business_id or label. The ad account itself never changes.

Detach the account (nothing is deleted in Meta).

Create (or pick up) the account's pixel. 409 pixel_exists.

Re-read account_status, disable_reason and payment method in Meta. 409 token_invalid | account_access_refused.

?level=campaign|adset|ad&days=7|30, from CreaScale's table (synced every 6 h), never Meta live. accountSyncedAt: null = never synced.

Sync the last 30 days now. 503 meta_unavailable writes nothing.

Create an ad account when the token sees none { login_id, business_id?, page_id?, currency?, pixel? }. Meta allows one account until a payment is confirmed; MAD/TND/KWD are not ad-account currencies (USD by default).

The account logic with its defaults: breakeven CPA, cut tolerance, scale rules, chosen KPIs. targetEditable: this plan can set the breakeven CPA (every paid plan); editable: it can write the rest (Enterprise).

Partial write, merged with the stored logic: { target_cpa_minor } on every paid plan, the rest on Enterprise. 400 invalid_logic with errors[].

?days=7|30&level=campaign|adset|ad, the account's KPI set, in total and per entity, from CreaScale's table.

?days=7|30&refresh=1, campaigns, ad sets and ads (also those created outside CreaScale), KPIs per node and a verdict per ad set and ad. acceptsAdset per campaign and accepts per ad set say what can be added there. refresh=1 re-reads the inventory from Meta first.

Enterprise. One row per attached account: KPIs in its own currency, breakeven CPA, verdict counts, live campaigns. From CreaScale's table, never Meta live; an unreadable account comes back with error: read_failed, never zeros.

Launch { objective: sales | messages, daily_budget, link?, destination?, targeting: { countries, age_min?, age_max?, … }, ads: [{ image_url | image_hash | video_url | video_id | post_id | media_ref, primary_text, headline?, description?, link?, cta? }], utm?, idempotency_key?, draft_token? }. 202 queued; 200 replay on the same idempotency_key; 409 account_not_ready. With adset_id: ads added to an existing ad set, nothing else changes. With campaign_id: a new ad set (budget, targeting, ads) in an existing campaign that has no campaign budget (409 campaign_cbo otherwise). Targeting the EU: the new ad set carries a beneficiary and a payer (dsa_beneficiary, dsa_payor; else the ad account's saved defaults, else the Page name). A read-only ad account fails with account_read_only before anything is written.

Same body as a launch. Checks everything (spec, landing page, media) and writes nothing at Meta: the recap, the checks and a draft_token valid 30 min. Pass it to the launch to launch exactly what was checked.

{ content_type, bytes }, a signed upload URL into a private bucket (video up to 50 MB, image up to 10 MB) and its storage: ref, to send as media_ref.

The 20 latest CreaScale static ads of your account, usable as image_url.

Status queued | running | done | failed, steps[], campaignId / adsetId / adIds as soon as they exist, errorCode (meta_unavailable, meta_refused, token_invalid, lp_unreachable, verify_failed, …), retryable.

Retry a failed launch when retryable: nothing already created is recreated. 409 launch_not_retryable.

The 50 most recent launches of the account.

?kind=campaign|adset|ad|creative|image|video, objects CreaScale knows for the account. ?refresh=1 re-reads status / effective_status from Meta (≤ 50 per call). 503 meta_unavailable.

{ status: ACTIVE | PAUSED } on a campaign, an ad set or an ad, written then read back. 409 status_not_applied.

{ daily_budget_minor } on an ad set, written then read back. 409 budget_not_applied.

Delete a campaign in Meta (status DELETED read back); its known ad sets and ads follow.

Pipeline run finished successfully (images + ad copies ready)

Pipeline run failed

Angles generated, run paused for review

New AI angles added to a run

Angles validated, generation starting

Images generated, ad copy in progress

An existing media was edited via POST /runs/:id/media/:mid/ai-edit

Meta approved a template — it becomes sendable

Meta rejected a template — the reason ships with the event

Send accepted by Meta (wamid assigned), template or free message — NOT delivered yet

Delivered to the customer's phone

Read (only if the customer has read receipts on)

Definitive send failure: error (label), error_code (Meta code, e.g. 131053 for a media refused after acceptance) and error_details

The customer REPLIED: text, media or button tap. Carries message_id (the history id) and at (the WhatsApp timestamp)

HTTPS endpoint, 10–2048 chars. Private, loopback and link-local addresses are refused (SSRF protection).

Which events to receive. Defaults to ["run.completed", "run.failed"]. Names come from the list above.

Non-HTTPS URL, or an address that fails the SSRF check.

Unknown event name. The WHOLE subscription is refused and the offending names are listed — a typo never silently trims your subscription down to the events that happened to be spelled right.

Maximum 5 webhooks per account. Delete one first.