Skip to main content

Make and edit image ads

Plan ad concepts with ad-concept, make an ad per picked concept with image-ad, and change an ad's text with ad-edit. Starting runs needs runs:create, reading them runs:read, and reading an ad's layers media:read. What the Addons make is described in Image ad.

Before you start​

Set GHOSTPULL_URL and GHOSTPULL_API_KEY as in the quickstart. The bash/zsh and fish examples also need jq.

Both Addons run on a product from your catalog (Import products); copy its id from listProducts (products:read). Its name, description and price are the only facts about the product an ad states, so keep them up to date in the catalog. The run starts from its main image, as in Run Addons on products.

Save the inputs both Addons take in one file, so the ad is checked against the same facts its concept was planned with:

jq -n --arg id "$PRODUCT_ID" '{product:{productId:$id},format:"4:5",goal:"conversion"}' > ad-inputs.json

listAddons (addons:read) lists every input. Besides the ones above, both Addons take image (another photo of the product, uploaded first), brand (Analyze a brand), model (auto, gemini or gpt-image), quality (standard or high), audience, message (an offer, used word for word), images (up to 3 more photos) and proof: real reviews, numbers or press as [{ "kind": "review", "text": "…", "source": "…" }], quoted only as given. image-ad draws only 4:5 and 9:16.

1. Plan ad concepts​

Start ad-concept as in Start runs. It costs 2 credits and plans 3 concepts unless count asks for 1 to 5:

jq '{addonId:"ad-concept",inputs:.,maxCredits:2,idempotencyKey:"linen-shirt-concepts-1"}' ad-inputs.json > plan-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/orchestrator/runs" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @plan-request.json --output plan.json
PLAN_ID=$(jq -r .runId plan.json)

2. Show the concepts​

Follow the run until it ends and save its last state:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/runs/ad-concept/$PLAN_ID?wait=15" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output plan-run.json

Repeat the call while status is RUNNING. Once it is SUCCEEDED, outputs.choices lists one entry per concept:

{
"status": "SUCCEEDED",
"outputs": {
"choices": [
{
"value": { "id": "c1", "catalog": { … }, "copy": { "headline": "…", "primaryText": "…", … }, … },
"title": "Price sticker: …",
"summary": "…",
"preview": { "type": "asset/image", "key": "…", "mediaType": "image/jpeg", "url": "https://…" },
"avoid": "…"
},
…
],
…
}
}

Show title, summary and the preview image to the person who picks. The preview sets the concept's layout, headline and brand on a sample photo, not on the product. Its url expires; read the run again for a fresh one. Keep value unchanged: it is what image-ad takes.

None of them fits? Start ad-concept again with the same inputs and the avoid values of the choices shown as a list in its avoid input; it then plans other concepts, for another 2 credits.

3. Make the ads​

For one pick, start image-ad with the same inputs and the picked value in concept. It costs 10 credits:

jq --slurpfile plan plan-run.json '{addonId:"image-ad",inputs:(. + {concept:$plan[0].outputs.choices[0].value}),maxCredits:10,idempotencyKey:"linen-shirt-ad-1"}' ad-inputs.json > ad-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/orchestrator/runs" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @ad-request.json --output ad.json

For several picks, start a batch with the inputs shared and one item per pick, here the first and third concept. Each item pays 10 credits when it succeeds:

jq --slurpfile plan plan-run.json '{addonId:"image-ad",inputs:.,items:[$plan[0].outputs.choices[0,2] | {inputs:{concept:.value}}],maxCredits:10,idempotencyKey:"linen-shirt-ads-1"}' ad-inputs.json > ads-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/orchestrator/batches" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @ads-request.json --output ads.json

A concept is checked against the run's facts again. If you change the inputs between the two runs, the ad fails when the concept states something the new facts do not support. To skip planning, leave concept out: image-ad then plans its own concept at no extra cost.

4. Read the ad​

Follow the run, or each batch item's runId, with getOrchestratorRun. A run that succeeded has these outputs:

OutputWhat it holds
imageThe ad, a JPEG with a signed url.
warningWhat the ad could not do as planned, such as a logo left out; empty when nothing.
statusThe quality check: approved, concept, needs_input or rejected.
issuesWhat the quality check found, each with the check and its result.
conceptThe concept the ad was made for; copy.primaryText is the text for your post.

libraryAssets.image.id is the ad's asset in the media library, with editable: true:

{ "status": "SUCCEEDED", "outputs": { … }, "libraryAssets": { "image": { "id": "0193…", "editable": true } } }

Save the ad's state and its asset ID:

AD_RUN_ID=$(jq -r .runId ad.json)
curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/runs/image-ad/$AD_RUN_ID?wait=15" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output ad-run.json
ASSET_ID=$(jq -r .libraryAssets.image.id ad-run.json)

Repeat the call while status is RUNNING; an ad takes several minutes.

5. Edit the ad's text​

Call getMediaAsset with that ID. For an ad, it answers the current version's composition: the canvas, its layers (text, logo, boxes and the picture) and the font files:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output ad-asset.json

Change only the layers you mean to change, found by their id, and keep the rest as they are. Then start ad-edit with ad, the asset's key and mediaType, and the whole composition without its src and without the url and srcSet of its files. It costs 1 credit. This example retypes the headline layer:

jq '{addonId:"ad-edit",inputs:{ad:{key:.asset.key,mediaType:.asset.mediaType},composition:(.composition | del(.src) | walk(if type == "object" and has("key") then del(.url, .srcSet) else . end) | (.layers[] | select(.id == "headline") | .text) |= "Linen for hot days")},maxCredits:1,idempotencyKey:"linen-shirt-ad-edit-1"}' ad-asset.json > edit-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/orchestrator/runs" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @edit-request.json --output edit.json

The run renders the ad from its layers in seconds, without a model call. Its image output is a new version of the same asset, carrying the new composition; earlier versions stay. Its warnings output lists what the change breaks of the ad's rules, each with its layer, kind and detail:

{ "status": "SUCCEEDED", "outputs": { "warnings": [{ "layer": "headline", "kind": "unreadable", "detail": "…" }], … } }

Kinds include on-product, on-person, outside-zones (where the app's buttons and captions may cover it), overlap, unreadable, button-too-small and font (a character the brand's font lacks, so the text is set in a neutral font). The new version is saved either way; show the warnings to the person who decides.

From an AI assistant​

Connected assistants such as Claude and ChatGPT (Connect through MCP) do the same with their tools. Asked for an ad, they plan concepts with ad-concept, show them as cards with their previews to pick from (show_choices, in clients that show MCP Apps), tell you the price and make one ad per pick. Asked to change an ad's text, its position or a colour, they start ad-edit with the changed layers and tell you its warnings.

Next​