---
title: "Run a model or API capability"
method: POST
path: "/v1/run"
tags: ["Models"]
---

# Run a model or API capability

`POST /v1/run`

## Request

- Base URL: `https://api.sandbase.ai`
- URL: `https://api.sandbase.ai/v1/run`
- Auth: HTTP bearer

Executes the selected catalog capability. Capability-specific fields must match the live schema returned by
the model detail endpoint or Store. Asynchronous capabilities can be polled with GET /v1/run/{id}.

## Request body

- RunRequest: Capability-specific request. Resolve the selected model's live input schema before sending fields.
  - `model` string, required: Current model or API capability identifier from the SandBase catalog.
  - `mode` 'auto' | 'sync' | 'async' | 'stream': Execution mode when supported by the selected capability. Auto uses the capability's configured default.
  - `stream` boolean: Requests streaming output. Equivalent to mode stream and valid only for a capability that supports streaming.
  - `webhook_url` string, uri: Optional public HTTPS callback URL for asynchronous image, video, or audio tasks. It is validated only for those tasks and ignored for other execution types.

## Response `200`

Capability completed synchronously, or a streaming response started

- RunResponse
  - `id` string, required: Opaque execution identifier. Use exactly as returned; no prefix is guaranteed.
  - `model` string, required
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'timeout', required: A stored completed task can temporarily be reported as running while output transfer is still pending.
  - `outputs` object[]: Extracted generated outputs when available. Omitted from non-terminal responses and also from completed responses whose output is empty, malformed, unsupported, or not yet transferred.
    - `url` string: Provider output string, commonly an HTTP URL or data URI; syntax is not revalidated by this projection.
    - `content_type` string
  - `error` object: Structured sanitized error for failed or timed-out runs when the stored error message is non-empty; otherwise omitted.
    - `type` string, required
    - `message` string, required
  - `usage` object: Model-specific public usage details when available; omitted for models that do not report them.

## Other responses

- `202`: Capability accepted for asynchronous execution
- `400`: Invalid JSON, unsupported execution mode, invalid capability input, or invalid webhook URL
- `401`: Missing or invalid API key
- `402`: Insufficient balance or spending limit reached
- `403`: The current API key cannot use the selected capability
- `404`: Model or capability not found
- `500`: Internal execution error
- `502`: Upstream provider returned an invalid response
- `503`: No provider is currently available

---

[API](https://skmtc.dev/sandbase/apis/sandbase-api.md) · [All operations](https://skmtc.dev/sandbase/apis/sandbase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sandbase/apis/sandbase-api/revisions/d40df2467ba2?raw)