Run a model or API capability

POST/v1/run

Execute an enabled SandBase model or API capability. The request fields are capability-specific; use the model detail page or Store for the selected capability schema.

Request body

stringmodelrequired

Enabled logical model or API capability identifier.

Optional<auto | sync | async | stream>mode

Execution mode hint. `auto` uses the selected capability's configured default; other values require capability support.

Optional<boolean>stream

Request streaming output when the selected capability supports it. Equivalent to `mode: stream`.

Optional<string>webhook_url

Optional HTTPS callback for supported asynchronous image

curl -X POST https://api.sandbase.ai/v1/run \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-image-2","prompt":"A studio product photo on a clean white background"}'

Response200 OK or 202 Accepted

{
  "id": "opaque-run-id",
  "model": "openai/gpt-image-2",
  "status": "pending"
}

Execution and results

Synchronous capabilities return a completed response in the original request. Asynchronous capabilities return 202 Accepted with an opaque id; poll Get an asynchronous run until the status is terminal.

Capability-specific request fields and output shapes are defined on the selected model or API operation page. Send those fields at the top level of the JSON body; do not wrap them in an input object. Do not assume that every capability accepts the same parameters.

Webhook callbacks

Set webhook_url only for supported asynchronous image, video, or audio tasks. SandBase sends the final run event to the HTTPS endpoint after completion or failure; the callback is a delivery hint, not a replacement for GET /v1/run/{id}. Always keep polling the run endpoint for authoritative status and retry safely when a callback is delayed or duplicated. Synchronous model responses and provider-native endpoints do not use this callback field.