Endpoints
Image Ads API
Generate template-based product image ads with the same fields and credit prices as the web app.
By Wilson Sik Founder, Reviral Last updated
Generate an image ad in 3 steps
Product photos must be HTTPS URLs returned by POST /api/v1/uploads. That endpoint stores the photo under your API key's account; another account cannot use the URL.
1. Upload the product photo
UPLOAD_JSON=$(curl -sS -X POST "https://reviral.ai/api/v1/uploads" \
-H "Authorization: Bearer $REVIRAL_API_KEY" \
-F "file=@./product.png")
PRODUCT_URL=$(node -e 'process.stdout.write(JSON.parse(process.argv[1]).data.url)' "$UPLOAD_JSON")2. Read the template price and create the ad
The code reads maxCredits from GET /api/v1/image-ads/templates, then calls POST /api/v1/image-ads; no price is hardcoded.
TEMPLATES_JSON=$(curl -sS "https://reviral.ai/api/v1/image-ads/templates")
MAX_CREDITS=$(node -e 'const t=JSON.parse(process.argv[1]).data.find(x=>x.id==="headline");process.stdout.write(String(t.credits))' "$TEMPLATES_JSON")
REQUEST_JSON=$(node -e 'const b={"templateId":"headline","product":{"title":"Trail shoe","bullets":["Grippy rubber outsole"],"price":"$89","photos":["__PRODUCT_URL__"],"rating":4.7,"reviewCount":92,"reviews":["Held up on wet trails"],"brand":"North"},"brand":{"colors":["#112233","#DDEEFF","#F4F4F4"],"fonts":["Inter"],"voice":["direct"],"neverSay":[],"logoUrl":null},"copy":{"headline":"Move beyond the pavement","subhead":"Grip wet trails with confidence."},"creative":{"surface":"light stone studio surface"},"maxCredits":-1};b.product.photos=[process.argv[1]];b.maxCredits=Number(process.argv[2]);process.stdout.write(JSON.stringify(b))' "$PRODUCT_URL" "$MAX_CREDITS")
JOB_JSON=$(curl -sS -X POST "https://reviral.ai/api/v1/image-ads" \
-H "Authorization: Bearer $REVIRAL_API_KEY" \
-H "Idempotency-Key: image-ad-001" \
-H "Content-Type: application/json" \
--data "$REQUEST_JSON")
JOB_ID=$(node -e 'process.stdout.write(JSON.parse(process.argv[1]).data.jobId)' "$JOB_JSON")3. Poll the job
curl -sS "https://reviral.ai/api/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $REVIRAL_API_KEY"Template field reference
Headline is shown below. Each requiredFields value is a copyable JSON path. The template's constraints object adds rules such as minimum array lengths, and fields has exactly one descriptive row per path.
| Path | Type | Constraints | Meaning | Example |
|---|---|---|---|---|
| product.title | string | None | Product name shown in the ad. | "Trail shoe" |
| product.bullets | string[] | None | Product facts the ad may use. | ["Grippy rubber outsole"] |
| product.price | string | None | Price text exactly as customers should see it. | "$89" |
| product.photos | HTTPS URL[] | None | Product photos returned by the uploads endpoint. | ["$PRODUCT_URL"] |
| product.rating | number | None | Product rating from 0 to 5. | 4.7 |
| product.reviews | string[] | None | Real customer review text. | ["Held up on wet trails"] |
| product.brand | string | None | Product brand name. | "North" |
| brand.colors | hex colour[] | Minimum items: 3 | At least three six-digit brand colours. | ["#112233","#DDEEFF","#F4F4F4"] |
| brand.fonts | string[] | None | Brand font names. | ["Inter"] |
| brand.voice | string[] | None | Plain words describing the brand voice. | ["direct"] |
| brand.neverSay | string[] | None | Words the ad must not use. | [] |
| brand.logoUrl | HTTPS URL | null | None | Owned logo upload URL, or null when no logo is supplied. | null |
| copy.headline | string (max 64) | None | Headline text supplied for this template. | "Headline" |
| copy.subhead | string (max 120) | None | Subhead text supplied for this template. | "Subhead" |
| creative.surface | string | None | Describe the surface shown in the scene in plain words. | "studio surface" |
The template catalog lists conditional fields. Every request includes product.title, bullets, price text, owned photo uploads, rating, reviews, product brand, brand colors, fonts, voice, exclusions, logo, and the template's named copy slots.
Use a server-side API key. Poll the returned status URL until ready or failed. Errors use the standard API envelope; temporary failures name only a generation provider.
/api/v1/image-ads
Generate an image ad
Build one template-based product image and charge exactly the same credits as the web app. Poll the returned job with GET /api/v1/jobs/{id}.
Authentication: Bearer API key required
curl -X POST "https://reviral.ai/api/v1/image-ads" \
-H "Authorization: Bearer $REVIRAL_API_KEY" \
-H "Idempotency-Key: first-generation" \
-H "Content-Type: application/json" \
--data '{"templateId":"headline","product":{"title":"Trail shoe","bullets":["Grippy rubber outsole"],"price":"$89","photos":["$PRODUCT_URL"],"rating":4.7,"reviewCount":92,"reviews":["Held up on wet trails"],"brand":"North"},"brand":{"colors":["#112233","#DDEEFF","#F4F4F4"],"fonts":["Inter"],"voice":["direct"],"neverSay":[],"logoUrl":null},"copy":{"headline":"Move beyond the pavement","subhead":"Grip wet trails with confidence."},"creative":{"surface":"light stone studio surface"}}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
| templateId | string | Yes | ID returned by GET /api/v1/image-ads/templates. |
| sizeId | string | No | Optional web-app size ID; the template default is used when omitted. |
| product | value | Yes | — |
| brand | value | Yes | — |
| copy | object | Yes | Template text slots listed in requiredFields. |
| creative | object | No | Scene details listed as creative.* paths by the selected template's requiredFields and fields table. |
| background | string | No | — |
| mood | array | No | — |
| finish | string | No | — |
| offerAvailable | boolean | No | — |
| language | string: en | zh-CN | ja | ko | th | vi | ar | fa | he | hi | ru | uk | el | tr | es | pt | fr | de | it | ms | id | No | Optional. The language of the fixed words and the lettering in the picture (your copy slots are painted as you send them). Leave it out and it is picked from your copy; copy that names no language is English. |
| maxCredits | integer (min 0) | No | Exact price lock; a different current web-app price returns 409. |
| webhookUrl | string | No | — |
Responses
- 202
- Image-ad job accepted
- 400
- Body is empty or is not JSON
- 401
- Key is missing, revoked, or invalid
- 402
- Account needs more credits
- 409
- Either the live charge changed (price_changed) or the Idempotency-Key was already used with a different request body (idempotency_key_reuse)
- 422
- validation_error: settings are invalid or a reference field is unsupported. content_refused: the model's content rules refused this request. Change the prompt or the reference images; the same request is usually refused again. error.creditsCharged is 0 once your credits are returned.
- 429
- Too many requests
- 502
- Job could not be started
- 503
- Models or rate limiting are temporarily unavailable
/api/v1/image-ads/templates
List image-ad templates
Returns all 40 templates, their required fields, example pictures, and exact current web-app credit prices.
Authentication: Public
curl "https://reviral.ai/api/v1/image-ads/templates"Responses
- 200
- Current image-ad template catalog
- 429
- Too many requests
- 503
- Models or rate limiting are temporarily unavailable