Query Image Task Status
curl --request GET \
--url https://api.poyo.ai/api/generate/status/{task_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.poyo.ai/api/generate/status/{task_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.poyo.ai/api/generate/status/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.poyo.ai/api/generate/status/{task_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.poyo.ai/api/generate/status/{task_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.poyo.ai/api/generate/status/{task_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.poyo.ai/api/generate/status/{task_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"credits_amount": 2,
"files": [
{
"file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100
}
}Image
Get Task Status
Query image task execution status and retrieve generated image files
GET
/
api
/
generate
/
status
/
{task_id}
Query Image Task Status
curl --request GET \
--url https://api.poyo.ai/api/generate/status/{task_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.poyo.ai/api/generate/status/{task_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.poyo.ai/api/generate/status/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.poyo.ai/api/generate/status/{task_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.poyo.ai/api/generate/status/{task_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.poyo.ai/api/generate/status/{task_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.poyo.ai/api/generate/status/{task_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"credits_amount": 2,
"files": [
{
"file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100
}
}Get Task Status
Query the execution status of image generation and editing tasks and retrieve generated images when complete.Endpoint
GET https://api.poyo.ai/api/generate/status/{task_id}
Authentication
All requests require Bearer token authentication:Authorization: Bearer YOUR_API_KEY
Parameters
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | Yes | Unique task identifier returned from the submit endpoint |
Response
Success Response (200)
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"credits_amount": 2,
"files": [
{
"file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100,
"error_message": null
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
code | integer | HTTP status code (200 for success) |
data.task_id | string | Unique task identifier |
data.status | string | Task status: not_started, running, finished, failed |
data.credits_amount | number | Credits charged for the task |
data.files | array | Generated images when status is finished |
data.files[].file_url | string | Direct URL to generated file |
data.files[].file_type | string | Type of generated file, usually image |
data.created_time | string | ISO 8601 timestamp of task creation |
data.progress | integer | Completion percentage (0-100) |
data.error_message | string | Error description when status is failed |
Status Values
| Status | Description |
|---|---|
not_started | Task is queued, waiting to be processed |
running | Task is currently being generated |
finished | Task completed successfully, results available in files |
failed | Task failed, error details in error_message |
Failed Task
{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "failed",
"credits_amount": 0,
"files": [],
"created_time": "2025-11-12T10:30:00",
"progress": 0,
"error_message": "The prompt violates our content policy"
}
}
Code Example
curl -X GET https://api.poyo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
-H "Authorization: Bearer YOUR_API_KEY"
Important Notes
Poll Interval: Check status every 2-5 seconds. Typical image generation takes 15-60 seconds.
Content Validity: Generated images are accessible for 3 days after creation. Download and save your content promptly.
Webhooks: Instead of polling, you can provide a
callback_url when submitting tasks to receive automatic notifications. See Image Webhook Callbacks.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Unique task identifier returned from the submit endpoint
Response
200 - application/json
Task status
Example:
200
Show child attributes
Show child attributes
Example:
{
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "finished",
"credits_amount": 2,
"files": [
{
"file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
"file_type": "image"
}
],
"created_time": "2025-11-12T10:30:00",
"progress": 100
}