Create a run
POST/runs
Starts generating creativesPerProduct creatives for each product. Answers 202 at once; poll GET /runs/{runId} and collect results from GET /runs/{runId}/items. Credits are held per item as it starts and charged only for creatives that are produced.
Request
Responses
- 202
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 503
Accepted — or the replay of an earlier create with this key.
Response Headers
The created run: /api/public/v1/runs/{runId}.
Bad Request. A cross-field rule failed (VALIDATION_ERROR, naming the fix), the run has more items than the plan allows (TOO_MANY_ITEMS), or a product has no primary image (NO_PRIMARY_IMAGE).
Unauthorized. Missing, malformed, unknown, revoked or expired bearer token — or the key owner no longer holds the Create API entitlement (CREATE_API_ENTITLEMENT_LOST).
Forbidden. The key lacks the required scope (API_TOKEN_SCOPE_DENIED): reads need runs:read, creating and stopping need runs:write. Or the plan does not include the requested imageSize (IMAGE_SIZE_NOT_ENTITLED): omit it for 1K. The size is refused, never reduced.
Not Found (PRODUCTS_NOT_IN_CATALOG). Every product id not in the account's catalog is named.
Conflict. The quote exceeds maxCredits (PRICE_EXCEEDS_MAX) or differs from expectedTotalCredits (PRICE_CHANGED), or the requested imageSize has no published price yet (IMAGE_SIZE_UNPRICED); the run does not fit what is left of the account's daily API credit budget (ACCOUNT_SPEND_CAP_EXCEEDED, with the numbers and the reset instant in budget); a create with this key is still in progress (IDEMPOTENCY_IN_PROGRESS, retry shortly); or the key was used for a different request (IDEMPOTENCY_KEY_REUSED). A budget refusal burns no key.
Unprocessable Content (VALIDATION_ERROR). A field has the wrong type or range, or is unknown; every offending field is listed in errors[].
Too Many Requests (RATE_LIMITED). More than 20 requests per minute on this key.
Response Headers
Seconds to wait before retrying.
Service Unavailable (CREATE_API_DISABLED). New runs are paused; existing runs can still be read. Or (ACCOUNT_SPEND_UNAVAILABLE) the account's daily API credit budget could not be checked, so nothing was created. Retry after the Retry-After interval.