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:
- bash / zsh
- fish
- PowerShell
jq -n --arg id "$PRODUCT_ID" '{product:{productId:$id},format:"4:5",goal:"conversion"}' > ad-inputs.json
jq -n --arg id "$PRODUCT_ID" '{product:{productId:$id},format:"4:5",goal:"conversion"}' > ad-inputs.json
@{
product = @{ productId = $env:PRODUCT_ID }
format = "4:5"
goal = "conversion"
} | ConvertTo-Json -Compress -Depth 5 | Set-Content -Encoding utf8NoBOM 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:
- bash / zsh
- fish
- PowerShell
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)
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
set PLAN_ID (jq -r .runId plan.json)
$inputs = Get-Content ad-inputs.json | ConvertFrom-Json
@{ addonId = "ad-concept"; inputs = $inputs; maxCredits = 2; idempotencyKey = "linen-shirt-concepts-1" } |
ConvertTo-Json -Compress -Depth 10 | Set-Content -Encoding utf8NoBOM plan-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/orchestrator/runs" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data-binary "@plan-request.json" --output plan.json
$env:PLAN_ID = (Get-Content plan.json | ConvertFrom-Json).runId
2. Show the concepts
Follow the run until it ends and save its last state:
- bash / zsh
- fish
- PowerShell
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
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
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/orchestrator/runs/ad-concept/${env:PLAN_ID}?wait=15" `
-H "x-api-key: $env: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:
- bash / zsh
- fish
- PowerShell
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
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
$plan = Get-Content plan-run.json | ConvertFrom-Json
$inputs = Get-Content ad-inputs.json | ConvertFrom-Json
$inputs | Add-Member concept $plan.outputs.choices[0].value
@{ addonId = "image-ad"; inputs = $inputs; maxCredits = 10; idempotencyKey = "linen-shirt-ad-1" } |
ConvertTo-Json -Compress -Depth 30 | Set-Content -Encoding utf8NoBOM ad-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/orchestrator/runs" `
-H "x-api-key: $env: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:
- bash / zsh
- fish
- PowerShell
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
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
$plan = Get-Content plan-run.json | ConvertFrom-Json
$inputs = Get-Content ad-inputs.json | ConvertFrom-Json
$items = @(0, 2 | ForEach-Object { @{ inputs = @{ concept = $plan.outputs.choices[$_].value } } })
@{ addonId = "image-ad"; inputs = $inputs; items = $items; maxCredits = 10; idempotencyKey = "linen-shirt-ads-1" } |
ConvertTo-Json -Compress -Depth 30 | Set-Content -Encoding utf8NoBOM ads-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/orchestrator/batches" `
-H "x-api-key: $env: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:
| Output | What it holds |
|---|---|
image | The ad, a JPEG with a signed url. |
warning | What the ad could not do as planned, such as a logo left out; empty when nothing. |
status | The quality check: approved, concept, needs_input or rejected. |
issues | What the quality check found, each with the check and its result. |
concept | The 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:
- bash / zsh
- fish
- PowerShell
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)
set 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
set ASSET_ID (jq -r .libraryAssets.image.id ad-run.json)
$env:AD_RUN_ID = (Get-Content ad.json | ConvertFrom-Json).runId
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/orchestrator/runs/image-ad/${env:AD_RUN_ID}?wait=15" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" --output ad-run.json
$env:ASSET_ID = (Get-Content ad-run.json | ConvertFrom-Json).libraryAssets.image.id
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:
- bash / zsh
- fish
- PowerShell
curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output ad-asset.json
curl --fail-with-body "$GHOSTPULL_URL/api/v1/media/assets/$ASSET_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY" --output ad-asset.json
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/media/assets/$env:ASSET_ID" `
-H "x-api-key: $env: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:
- bash / zsh
- fish
- PowerShell
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
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
$ad = Get-Content ad-asset.json | ConvertFrom-Json
$composition = $ad.composition
$composition.PSObject.Properties.Remove("src")
$files = @($composition.layers | ForEach-Object { $_.asset }) +
@($composition.fonts | ForEach-Object { $_.asset }) +
@($composition.masks | ForEach-Object { $_.src })
foreach ($file in $files | Where-Object { $_ }) {
$file.PSObject.Properties.Remove("url")
$file.PSObject.Properties.Remove("srcSet")
}
($composition.layers | Where-Object id -eq "headline").text = "Linen for hot days"
@{
addonId = "ad-edit"
inputs = @{ ad = @{ key = $ad.asset.key; mediaType = $ad.asset.mediaType }; composition = $composition }
maxCredits = 1
idempotencyKey = "linen-shirt-ad-edit-1"
} | ConvertTo-Json -Compress -Depth 30 | Set-Content -Encoding utf8NoBOM edit-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/orchestrator/runs" `
-H "x-api-key: $env: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.