Fusara
Runs
Markdown ↗

Create a run

POST/api/v3/run

Overview

Returns 202 with the run ID and expected cost, or 200 if already terminal. Successful idempotent replay returns the original Run without repricing. Outputs and errors are omitted until applicable. Supply a public HTTPS webhook_url directly; no registration or shared receiver secret is required. Webhooks contain the full Run JSON with ready output URLs: match the expected Run, save the result and acknowledge with 2xx. Signature verification is optional; do not make JWKS setup or a result GET a prerequisite for integration. Without verification, sender authenticity is unverified. Fusara always signs notifications with Ed25519; public keys: /.well-known/jwks.json. Billing may settle later, producing a second snapshot with a distinct webhook-id. Delivery is at least once, with up to 10 total attempts; snapshots can arrive out of order. Use webhook-id to deduplicate and never replace settled cost with pending cost.

Requires an API key. Send Authorization: Bearer YOUR_API_KEY. Authentication →

curl 'https://fusara.ai/api/v3/run' \
  -H "Authorization: Bearer $FUSARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "model": "qwen-image21-create",
  "prompt": "A white ceramic lamp on a pale lavender background, soft studio light."
}'

The fields below describe the shared request. Required inputs and additional settings depend on your model. Choose a model in the playground →

Parameters

Idempotency-Keystring

Optional. Reuse the same key and body to recover the same run. On 409 request_in_progress, wait for Retry-After and retry with that same key and unchanged body. A different body returns 422 idempotency_conflict. Scope: API-key owner. Keys remain bound even after rejection, for the lifetime of the submission.

  • header
  • Pattern: ^[!-~]+$
  • Minimum length: 1
  • Maximum length: 256

Request body

Flat model-specific settings and named reference arrays. Discover exact supported fields, defaults and bounds in GET /api/v3/models/{model}: request_schema. Unknown fields are rejected; there are no input/parameters wrappers. Maximum body: 1 MiB.

modelstringrequired

Exact public model ID from model discovery. Keep any variant suffix, including slashes.

promptstring

Text instruction. Availability and whether it is required depend on the selected model's request_schema. Estimates can omit it when the price is determined by settings alone.

webhook_urlstring

Optional public HTTPS callback URL; no registration required. Receives the full Run JSON, ready to save without another GET. Signature verification is optional; without it, sender authenticity is unverified.

  • Format: uri
  • Maximum length: 2048

Responses

Run accepted; queued or running.

Illustrative response. Prices, IDs and URLs come from your own request.

Example response
{
  "id": 123456,
  "status": "queued",
  "cost": {
    "unit": "common_fuz",
    "expected": "40.0000",
    "status": "pending"
  }
}
idintegerrequired

Numeric run ID. Use it for status, results, cancellation and matching webhooks.

  • Format: int64
  • Minimum: 0
  • Maximum: 4294967295
statusstringrequired

queued or running while in progress; succeeded, failed or canceled when terminal.

costobjectrequired
Nested fields 4
unitstringrequired

Billing unit: common_fuz.

expectedstringrequired

Total accepted estimate for this run, as a decimal string.

statusstringrequired

pending until billing is confirmed, then settled. Generation can finish before settlement.

chargedstring

Confirmed final charge, as a decimal string. Omitted while pending; confirmed zero is 0.0000.

outputsobject[]

Applicable outputs in their original order. Omitted when none exist; a failed run can still have usable partial outputs.

Nested fields 7
typestringrequired
  • Alternative values: "text", "json", "boolean", "image", "video", "audio", "media", "model_asset"
media_idinteger

Reusable account media ID when this output is a file.

  • Format: int64
  • Minimum: 0
  • Maximum: 4294967295
urlstring

Download URL when the file is available. Save it before url_expires_at.

url_expires_atstring

UTC expiry of this output URL, when provided.

  • Format: date-time
expiredboolean

True when the media is no longer available; its dead URL is omitted.

valueany JSON value

Inline result: a string for type=text, a native JSON value for type=json, or a boolean for type=boolean. Empty strings, false and JSON null are valid values. Omitted for files and model assets.

  • When type is "text": required; string
  • When type is "json": required; any JSON value
  • When type is "boolean": required; boolean
  • When type is "image" or "video" or "audio" or "media" or "model_asset": must be omitted
model_asset_idinteger
  • Format: int64
  • Minimum: 0
  • Maximum: 4294967295
errorobject
Nested fields 2
codestringrequired

Machine-readable generation failure code.

messagestringrequired

Human-readable explanation of the generation failure.

Response headers

Locationstringrequired

Absolute URL for reading this run. Authenticate GET requests with your API key.

  • Format: uri
X-Request-Idstringrequired

Support/trace identifier for this HTTP request.