Invoke Models - BizyAir-Docs

Overview of Calling Modes

BizyAir offers three calling modes, switched via HTTP headers. No request body changes are needed:

Mode	How to enable	Behavior	Best for
Synchronous blocking	No special header	Connection stays open until the task completes, then returns the result	Short tasks, quick debugging
Async polling	`X-BizyAir-Task-Async: enable`	Returns `request_id` immediately; client polls for results	Long-running tasks, unstable networks, no callback URL available
Webhook	`X-BizyAir-Task-WebHook-Url: <url>`	Returns `request_id` immediately; platform POSTs to your callback URL on completion	Production, high concurrency, long-running tasks

Synchronous Blocking

The default mode. The HTTP connection stays open until the task completes. No special header is required.

curl -X POST "https://api.bizyair.ai/v1/webapp/task/openapi/create" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "web_app_id": 38214,
    "suppress_preview_output": false,
    "input_values": {
      "84:CLIPTextEncode.text": "a futuristic cityscape at sunset",
      "88:KSampler.seed": 354884000907176,
      "81:EmptySD3LatentImage.width": 1280,
      "81:EmptySD3LatentImage.height": 1280
    }
  }'

The response contains the task result, including outputs[].object_url.

Synchronous mode requires a long-lived connection. Make sure your HTTP client’s read timeout is at least 60 seconds to prevent the client from disconnecting while the task is still running.

Async Polling

Enable by adding the X-BizyAir-Task-Async: enable header to your request.

Step 1: Submit an async task and get the`request_id`

curl -X POST "https://api.bizyair.ai/v1/webapp/task/openapi/create" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-BizyAir-Task-Async: enable" \
  -d '{
    "web_app_id": 38214,
    "input_values": {
      "84:CLIPTextEncode.text": "a futuristic cityscape at sunset",
      "88:KSampler.seed": 354884000907176,
      "81:EmptySD3LatentImage.width": 1280,
      "81:EmptySD3LatentImage.height": 1280
    }
  }'

Returns 202 Accepted immediately:

{"request_Id": "29f53793-12d3-4dd3-b2a8-4d9848e0c7da"}

Step 2: Poll the task status

curl -X GET "https://api.bizyair.ai/v1/webapp/task/openapi/detail?requestId=29f53793-12d3-4dd3-b2a8-4d9848e0c7da" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"

Step 3: Retrieve results once the status is `Success`

curl -X GET "https://api.bizyair.ai/v1/webapp/task/openapi/outputs?requestId=29f53793-12d3-4dd3-b2a8-4d9848e0c7da" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"

Complete Python Example

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.bizyair.ai/v1/webapp/task/openapi"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-BizyAir-Task-Async": "enable",
}

# 1. Submit task
resp = requests.post(f"{BASE}/create", headers=HEADERS, json={
    "web_app_id": 38214,
    "input_values": {
        "84:CLIPTextEncode.text": "a futuristic cityscape at sunset",
        "88:KSampler.seed": 354884000907176,
        "81:EmptySD3LatentImage.width": 1280,
        "81:EmptySD3LatentImage.height": 1280,
    }
})
request_id = resp.json()["request_Id"]
print(f"Task submitted: {request_id}")

# 2. Poll status
HEADERS.pop("X-BizyAir-Task-Async")
while True:
    r = requests.get(f"{BASE}/{request_id}", headers=HEADERS)
    status = r.json()["data"]["status"]
    print(f"Current status: {status}")
    if status == "Success":
        break
    elif status in ("Failed", "Canceled"):
        print("Task failed or canceled")
        exit(1)
    time.sleep(2)

# 3. Get results
r = requests.get(f"{BASE}/{request_id}/outputs", headers=HEADERS)
for out in r.json()["data"]["outputs"]:
    print("Result URL:", out["object_url"])

Webhook Callback

Enable by adding the X-BizyAir-Task-WebHook-Url header to your request.

Step 1: Submit a task with a webhook

curl -X POST "https://api.bizyair.ai/v1/webapp/task/openapi/create" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-BizyAir-Task-WebHook-Url: https://your-server.com/api/callback" \
  -H "X-BizyAir-Task-Authorization: Bearer YOUR_CALLBACK_TOKEN" \
  -d '{
    "web_app_id": 35661,
    "input_values": {
      "1:EmptyLatentImage.width": "1024",
      "1:EmptyLatentImage.height": "1024",
      "2:BizyAir_BasicScheduler.steps": "20",
      "3:BizyAir_RandomNoise.noise_seed": "1",
      "4:BizyAirSiliconCloudLLMAPI.user_prompt": "A kitten, Van Gogh style",
      "4:BizyAirSiliconCloudLLMAPI.system_prompt": "You are a stable diffusion prompt expert..."
    }
  }'

Returns 202 Accepted + request_Id immediately.

Step 2: Receive results at your callback endpoint

When the task completes, BizyAir sends a POST request to the URL you specified:

Method: POST
Headers: Content-Type: application/json, User-Agent: Go-http-client/1.1, along with your X-BizyAir-Task-Authorization and any other X-BizyAir-Task-* headers you set
Body: Contains the complete task result

Node.js Callback Server Example

const express = require("express");
const app = express();
app.use(express.json());

const EXPECTED_TOKEN = process.env.CALLBACK_TOKEN;

app.post("/api/callback", (req, res) => {
  const auth = req.get("Authorization");
  if (EXPECTED_TOKEN) {
    const ok = auth?.startsWith("Bearer ") && auth.split(" ")[1] === EXPECTED_TOKEN;
    if (!ok) return res.status(401).json({ message: "invalid token" });
  }

  const payload = req.body;
  console.log("Received callback for request_id:", payload.request_id);

  res.status(200).json({ ok: true });
});

app.listen(3000, () => console.log("Callback server on :3000"));

Your callback endpoint must return HTTP 200 OK. If it returns a non-200 status, times out, or is unreachable, the platform will retry on a schedule (approximately every 6 seconds, up to 10 attempts). The per-request timeout is approximately 10 seconds.

Choosing a Calling Mode

Your scenario	Recommended mode	Why
Quick local script testing	Synchronous blocking	Simplest — one request returns the result directly
Short tasks integrated into a backend	Synchronous blocking	HTTP connection overhead is acceptable for short tasks
Video generation / 3D rendering (long tasks)	Webhook	Doesn’t block your service; supports large-scale parallelism
Unstable client network	Async polling	No long-lived connection needed; poll on demand
Batch processing hundreds of tasks	Async polling or Webhook	Queue everything, then collect results at your own pace
Production high availability	Webhook	Push-based with built-in retries

Query Task Status

Get the current status and metadata of a task (queue info, runtime, etc.).

curl -X GET "https://api.bizyair.ai/v1/webapp/task/openapi/{request_id}" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"

Response fields (inside data):

Field	Type	Description
`type`	string	Task type, e.g. `"API"`
`status`	string	Task status enum
`created_at`	string	Created time (UTC+8)
`updated_at`	string	Last updated time
`executed_at`	string	Execution start time
`ended_at`	string \| null	End time; `null` if not finished
`expired_at`	string	Result file expiry time
`inference_cost_time`	integer	Inference duration (seconds)
`queue_info`	object \| null	Only present when status is `Queuing`

Status enum:

Status	Meaning	Suggested action
`Queuing`	Queued, waiting for resource scheduling	Keep polling every 1-3 seconds
`Preparing`	Preparing, loading model / environment	Keep polling
`Running`	Running	Keep polling
`Success`	Completed successfully	Stop polling; retrieve results
`Failed`	Failed	Stop polling; check `error_message`
`Canceled`	Cancelled	Stop polling

Query Task Results

Retrieve the outputs (object_url, etc.) of a completed task.

curl -X GET "https://api.bizyair.ai/v1/webapp/task/openapi/{request_id}/outputs" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY"

Response example:

{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "request_id": "29f53793-12d3-4dd3-b2a8-4d9848e0c7da",
    "status": "Success",
    "outputs": [
      {
        "object_url": "https://storage.bizyair.ai/outputs/xxx.png",
        "output_ext": ".png",
        "cost_time": 10657,
        "audit_status": 2,
        "error_type": "NOT_ERROR"
      }
    ]
  }
}

outputs[] field reference:

Field	Type	Description
`object_url`	string	Result file download URL
`output_ext`	string	File extension (includes `.`)
`cost_time`	integer	Time from task start to this output (ms)
`audit_status`	integer	Audit status: `1` pending / `2` approved / `3` rejected / `4` error
`error_type`	string	Error code on failure; `"NOT_ERROR"` on success
`error_msg`	string	Detailed failure reason (optional)

Cancel Task

Only works for tasks in the Queuing state; removes the task from the queue.

curl -X PUT "https://api.bizyair.ai/v1/webapp/task/openapi/{request_id}/cancel" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json"

Cancellation is idempotent — repeated calls have no side effects. If the task is already running, use Interrupt instead.

Interrupt Task

Only works for tasks in the Running state; forces a stop.

curl -X PUT "https://api.bizyair.ai/v1/webapp/task/openapi/{request_id}/interrupt" \
  -H "Authorization: Bearer $BIZYAIR_API_KEY" \
  -H "Content-Type: application/json"

Interrupting a running task still incurs charges for the portion already executed. Only tasks in the Queuing state can be cancelled at no charge.

​Overview of Calling Modes

​Synchronous Blocking

​Async Polling

​Step 1: Submit an async task and get therequest_id

​Step 2: Poll the task status

​Step 3: Retrieve results once the status is Success

​Complete Python Example

​Webhook Callback

​Step 1: Submit a task with a webhook

​Step 2: Receive results at your callback endpoint

​Node.js Callback Server Example

​Choosing a Calling Mode

​Query Task Status

​Query Task Results

​Cancel Task

​Interrupt Task

Overview of Calling Modes

Synchronous Blocking

Async Polling

Step 1: Submit an async task and get the`request_id`

Step 2: Poll the task status

Step 3: Retrieve results once the status is `Success`

Complete Python Example

Webhook Callback

Step 1: Submit a task with a webhook

Step 2: Receive results at your callback endpoint

Node.js Callback Server Example

Choosing a Calling Mode

Query Task Status

Query Task Results

Cancel Task

Interrupt Task