Start runs
Start an Addon run for the account. Starting needs runs:create; each run
pays its price in credits when it succeeds.
Before you start
Set GHOSTPULL_URL and GHOSTPULL_API_KEY as in the
quickstart. This guide runs lifestyle-scene on the
product photo from Upload media, saved in asset.json.
The bash/zsh and fish examples also need jq.
Call listAddons (addons:read)
for each Addon's inputs and pricing.
1. Start the run
Call startOrchestratorRun
with the Addon's ID, its inputs keyed by input ID, and two fields an API key
must always send:
maxCredits: the most the run may cost. A higher price refuses the start before anything runs.idempotencyKey: a new unique value for each run you intend, such as a UUID you store with your job. Sending it again within an hour returns the run it started. All keys of the account share these values, so never reuse one for another run.
An image input is the uploaded asset's key and mediaType, or a public
https URL:
- bash / zsh
- fish
- PowerShell
jq '{addonId:"lifestyle-scene",inputs:{image:{key:.asset.key,mediaType:.asset.mediaType},scene:"on a wooden kitchen counter in soft morning light"},maxCredits:10,idempotencyKey:"9f1c2a7e-shoe-42-kitchen"}' asset.json > run-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 @run-request.json --output run.json
jq '{addonId:"lifestyle-scene",inputs:{image:{key:.asset.key,mediaType:.asset.mediaType},scene:"on a wooden kitchen counter in soft morning light"},maxCredits:10,idempotencyKey:"9f1c2a7e-shoe-42-kitchen"}' asset.json > run-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 @run-request.json --output run.json
$asset = Get-Content asset.json | ConvertFrom-Json
$body = @{
addonId = "lifestyle-scene"
inputs = @{
image = @{ key = $asset.asset.key; mediaType = $asset.asset.mediaType }
scene = "on a wooden kitchen counter in soft morning light"
}
maxCredits = 10
idempotencyKey = "9f1c2a7e-shoe-42-kitchen"
} | ConvertTo-Json -Compress -Depth 5
$body | Set-Content -Encoding utf8NoBOM run-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 "@run-request.json" --output run.json
The run starts and the call answers 202 at once:
{ "runId": "0193…", "addonId": "lifestyle-scene" }
Inputs you leave out take the values the account saved for the Addon in the web app, otherwise the Addon's defaults. A run started with an API key always uses the Addon's current production version.
2. Handle a refused start
Nothing starts and no credits are reserved when the call is refused:
| Answer | What to do |
|---|---|
400 invalid_request | Send maxCredits and idempotencyKey, and check inputs against listAddons. |
409 orchestrator.price_above_max_credits | The price is in details.priceCredits. Raise maxCredits or change the inputs. |
409 billing.insufficient_credits | Add credits under Billing in the web app; details has required and available. |
409 orchestrator.run_start_in_progress | The first start with this key is still on its way. Retry after details.retryAfterSeconds. |
409 orchestrator.idempotency_key_reused | The key started a different request. Use a new key for a new run. |
To retry after a timeout or a lost answer, send the same request with the
same idempotencyKey within an hour. It answers the run it started and
charges nothing again.
3. Follow the run
Keep runId and addonId from run.json, then
follow the run until it ends. The run pays its price only
when it succeeds.
4. Redo a result with a note
If a finished result needs a fix and the Addon's ui.redo in listAddons
lists choices, call
redoOrchestratorRun
with the run's IDs, the choices and an optional text, plus a new
maxCredits and idempotencyKey as for a start. It starts a new run with
the same inputs and the note, and answers its runId; the new run's
redoOf names the earlier one, which stays as it is. A redo needs
runs:create and pays its price again when it succeeds.