Endpoints

Image Ads API

Was this page helpful?

Generate template-based product image ads with the same fields and credit prices as the web app.

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.

POST

/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	—
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: Settings are invalid or a reference field is unsupported
429: Too many requests
502: Job could not be started
503: Models or rate limiting are temporarily unavailable

GET

/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

Quickstart Models Errors

Generate an image ad in 3 steps

1. Upload the product photo

2. Read the template price and create the ad

3. Poll the job

Template field reference

/api/v1/image-ads

Generate an image ad

Request body

Responses

/api/v1/image-ads/templates

List image-ad templates

Responses

Related topics