Query Task Status

GET

tasks

{task_id}

Query Task Status

curl --request GET \
  --url https://api.qingbo.ai/v1/tasks/{task_id}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qingbo.ai/v1/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "task_id": "<string>",
  "status": "<string>",
  "action": "<string>",
  "model": "<string>",
  "progress": "<string>",
  "created_at": 123,
  "completed_at": 123,
  "cost": 123,
  "error": {},
  "result": {},
  "urls": {}
}

The core query endpoint for asynchronous tasks. After submitting a task (POST /v1/tasks) and receiving a task_id, poll this endpoint until status: completed to retrieve the final result.

Example Request

curl https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499 \
  -H "Authorization: Bearer $WAVE_API_KEY"

Example Responses (By Stage)

{
  "task_id": "task-wave1775285160b950328499",
  "status": "queued",
  "action": "generate",
  "model": "wan2.7",
  "progress": "",
  "created_at": 1720000000,
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499/cancel"
  }
}

{
  "task_id": "task-wave1775285160b950328499",
  "status": "processing",
  "action": "generate",
  "model": "wan2.7",
  "progress": "45%",
  "created_at": 1720000000,
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499/cancel"
  }
}

{
  "task_id": "task-wave1775285160b950328499",
  "status": "completed",
  "action": "generate",
  "model": "wan2.7",
  "progress": "100%",
  "created_at": 1720000000,
  "completed_at": 1720000030,
  "cost": 75000,
  "result": {
    "videos": [
      {
        "expires_at": 1720259200,
        "url": ["https://cdn.qingbo.dev/output/xxx.mp4"]
      }
    ]
  },
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499/cancel"
  }
}

{
  "task_id": "task-wave1775285160b950328499",
  "status": "completed",
  "action": "generate",
  "model": "seedream-5.0-lite",
  "progress": "100%",
  "created_at": 1720000000,
  "completed_at": 1720000030,
  "cost": 5500,
  "result": {
    "images": [
      {
        "expires_at": 1720259200,
        "url": ["https://cdn.qingbo.dev/output/xxx.png"]
      }
    ]
  },
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499/cancel"
  }
}

{
  "task_id": "task-wave1775285160b950328499",
  "status": "failed",
  "action": "generate",
  "model": "wan2.7",
  "progress": "100%",
  "created_at": 1720000000,
  "completed_at": 1720000005,
  "cost": 0,
  "error": {
    "message": "[upstream_bad_request] Upstream returned: invalid prompt",
    "code": "upstream_bad_request"
  },
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1775285160b950328499/cancel"
  }
}

Response Fields

string

Unique task ID (returned at submission)

string

Task status:

queued — Submitted, waiting to be processed
processing — In progress; the progress field indicates progress (percentage string)
completed — Done; result contains the generated output
failed — Failed; error contains the error details
cancelled — Cancelled (only queued tasks can be cancelled)

string

Action type, identical to the value submitted (generate / edit / image2video, etc.)

string

Model ID used (group_name)

string

Progress as a percentage string (for example "30%", "100%"). It may be an empty string right after queuing; terminal states (completed / failed) report "100%". Note that the submit response carries progress as the integer 0, while the status response carries a string — do not parse it as a number.

integer

Creation time (Unix timestamp in seconds)

integer

Completion time (Unix timestamp in seconds). Only present in completed / failed / cancelled states

integer

Actual quota charged for the task. Only present in terminal states (completed / failed / cancelled). Success = settled amount; failed/cancelled with automatic refund = 0. Use this field for reconciliation.

object

Error details. Only present in the failed state:

message — Error description
code — structured error code. Common values: upstream_unavailable (retryable), upstream_bad_request (rejected by upstream), upstream_rate_limited, task_failed (other failures)

object

Generation result. Only present in the completed state. Depending on the task’s media type, the key is images / videos / audios (an array). Each item contains:

url — string[] array (always an array, even with a single element)
expires_at — Unix timestamp in seconds; when the artifact is deleted. Counted as 7 days from the moment the task finished, so it is the same value however many times you query; after it passes, object storage deletes the file

object

Convenience action links so clients don’t have to assemble URLs:

get — Current query endpoint
cancel — Cancel-task endpoint

Polling Recommendations

Polling interval: every 2–5 seconds
Maximum wait time: 5-minute timeout recommended (videos may take longer)
Display progress to show real-time progress to users
Prefer Webhooks: set callback_url at submission to receive a push on completion and skip polling

See Task System for the full workflow.

Download and persist results to your own storage promptly. Artifacts are kept in our object storage for 7 days only, counted from the moment the task finished (that is expires_at); after that a storage lifecycle rule deletes them and they cannot be fetched again. Do not use result links as long-term storage.

Error Codes

Status	Error	Description
404	`task_not_found`	task_id does not exist or doesn’t belong to the current user
401	Authentication failed	Invalid API key

Submit Task — POST /v1/tasks
Cancel Task — POST /v1/tasks/{task_id}/cancel
Task System

Query Task Status

curl --request GET \
  --url https://api.qingbo.ai/v1/tasks/{task_id}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qingbo.ai/v1/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "task_id": "<string>",
  "status": "<string>",
  "action": "<string>",
  "model": "<string>",
  "progress": "<string>",
  "created_at": 123,
  "completed_at": 123,
  "cost": 123,
  "error": {},
  "result": {},
  "urls": {}
}

Text Generation

Image Generation

Video Generation

Audio

Tools & Embeddings

Task Management

Account & Usage

Example Request

Example Responses (By Stage)

Response Fields

Polling Recommendations

Error Codes

​Example Request

​Example Responses (By Stage)

​Response Fields

​Polling Recommendations

​Error Codes

​Related Documentation

Example Request

Example Responses (By Stage)

Response Fields

Polling Recommendations

Error Codes

Related Documentation