Invoke AI Apps - 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": 57302,
    "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": 57302,
    "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/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/29f53793-12d3-4dd3-b2a8-4d9848e0c7da/outputs" \
  -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": 57302,
    "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.

Get AI App Information

You can retrieve metadata for any AI app (WebApp) you have permission to access via web_app_id, including the app name, author info, cover image, and all input node definitions (input_nodes) required to call the app. Developers can use this to dynamically discover an app’s input parameters: the variable_name in input_nodes corresponds one-to-one with the keys of input_values in the “Invoke AI Apps” request body, making it ideal for building DIY plugins. A plugin can first call this endpoint to fetch the input fields, then auto-render a form and construct the call request.

Endpoint

GET https://meta.bizyair.ai/v1/webapp/{web_app_id}/detail

{web_app_id} is the app ID, the same as the numeric ID in the app detail page URL and the web_app_id in the Invoke AI Apps request body. Public apps can be accessed without additional authentication; a 404 is returned if the app does not exist or you lack access.

Request Example

curl -X GET "https://meta.bizyair.ai/v1/webapp/57302/detail"

Response Example

{
  "code": 20000,
  "message": "Ok",
  "status": true,
  "data": {
    "id": 57302,
    "name": "Anima_HiresFix_1.5x Refinement",
    "user_id": "01kwv421t34pg5xtyrtbsvb3t7",
    "nick_name": "Gugugaga",
    "user_avatar": "https://storage.bizyair.ai/users/01kwv421t34pg5xtyrtbsvb3t7/...webp",
    "user_description": "Happy everyday",
    "base_model": "Anima",
    "description": "About $0.03 per run",
    "original_user_id": "01kwv421t34pg5xtyrtbsvb3t7",
    "created_at": "2026-08-05T10:10:55Z",
    "cover_urls": [
      "https://storage.bizyair.ai/img/20260805/431c5578-..._1536_1536.png"
    ],
    "counter": {
      "used_count": 14,
      "liked_count": 1
    },
    "input_nodes": [
      {
        "id": 37986,
        "node_id": 5,
        "node_name": "Positive Prompt",
        "node_type": "CLIPTextEncode",
        "field_name": "text",
        "field_type": "customtext",
        "field_options": "{\"hideOnZoom\":true,\"minNodeSize\":[400,200]}",
        "field_label": "Positive Prompt",
        "field_value": "masterpiece, best quality, ...",
        "variable_name": "5:CLIPTextEncode.text"
      }
    ],
    "source": "others",
    "ref_bizy_model_id": 56210
  }
}

input_nodes contains all input nodes for the app; the actual response may include multiple nodes. Some field values are omitted in this example.

Response Field Reference

Fields inside data:

Field	Type	Description
id	integer	App ID (web_app_id)
name	string	App name
user_id	string	Author user ID
nick_name	string	Author nickname
user_avatar	string	Author avatar URL
user_description	string	Author bio
base_model	string	Base model
description	string	App description (e.g., cost per run)
original_user_id	string	Original author user ID (points to the source author on Fork)
created_at	string	Creation time (ISO 8601, UTC)
cover_urls	string[]	Cover image URL list
counter	object	Usage stats: `used_count` (usage count), `liked_count` (like count)
input_nodes	array	Input node definition list, used to construct call parameters
source	string	App source, e.g. `"others"`
ref_bizy_model_id	integer	Associated BizyAir model ID

Fields inside input_nodes[]:

Field	Type	Description
id	integer	Input field ID
node_id	integer	Node ID
node_name	string	Node name
node_type	string	Node type, e.g. `CLIPTextEncode`
field_name	string	Field name
field_type	string	Field type, e.g. `customtext`
field_options	string	Node config (JSON string)
field_label	string	Field display name, can be used to render form labels
field_value	string	Field default value
variable_name	string	Variable name, i.e. the key of `input_values` when calling the app (e.g. `5:CLIPTextEncode.text`)
sort	integer	Sort order (optional)

Error Response

Returns HTTP 404 when the app does not exist or you lack access:

{
  "code": 20230,
  "message": "Resource version not found.",
  "data": null
}

​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

​Get AI App Information

​Endpoint

​Request Example

​Response Example

​Response Field Reference

​Error Response

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

Get AI App Information

Endpoint

Request Example

Response Example

Response Field Reference

Error Response