Skip to main content

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:

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

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:

AnswerWhat to do
400 invalid_requestSend maxCredits and idempotencyKey, and check inputs against listAddons.
409 orchestrator.price_above_max_creditsThe price is in details.priceCredits. Raise maxCredits or change the inputs.
409 billing.insufficient_creditsAdd credits under Billing in the web app; details has required and available.
409 orchestrator.run_start_in_progressThe first start with this key is still on its way. Retry after details.retryAfterSeconds.
409 orchestrator.idempotency_key_reusedThe 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.

Next​