Submit and Track Generation Tasks with Two REST Endpoints

Base URL#

https://api.poyo.ai

Authenticate every request#

PoYo uses API key authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate your key from the API Console.

Two endpoints cover every generation type#

Submit Task

POST https://api.poyo.ai/api/generate/submit

Submit image or video generation requests. Returns immediately with a task_id.

Query Status

GET https://api.poyo.ai/api/generate/status/{task_id}

Check task progress and retrieve results.

Follow the asynchronous workflow#

Submit Task — POST to /api/generate/submit with model and parameters.
Receive Task ID — the API returns task_id immediately with status not_started.
Poll or Wait — poll /api/generate/status/{task_id} or receive a webhook callback.
Retrieve Results — when status is finished, get generated files from the response.

Read consistent JSON responses#

Submit response:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2025-11-12T10:30:00"
  }
}

Status response:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "finished",
    "progress": 100,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "error_message": null
  }
}

Status	Description
`not_started`	Task queued, waiting to begin
`running`	Task currently processing
`finished`	Task completed, results available in `files` array
`failed`	Task failed, error details in `error_message`

Error response:

{
  "code": 400,
  "error": {
    "message": "Invalid parameter: size",
    "type": "invalid_request_error"
  }
}

Check HTTP status codes#

Code	Description
200	Success — request completed successfully
400	Bad Request — invalid parameters
401	Unauthorized — invalid or missing API key
402	Payment Required — insufficient account balance
500	Internal Server Error — server error occurred

See Error Codes for the full list, including 403, 404, 408, 429, 502, and 503.

Choose polling or webhooks#

Polling:

import time
while True:
    response = requests.get(f"{BASE_URL}/api/generate/status/{task_id}", headers=headers)
    task = response.json()["data"]
    if task["status"] in ["finished", "failed"]:
        break
    time.sleep(2)

Webhooks (recommended): provide a callback_url to receive automatic notifications:

payload = {
    "model": "gpt-4o-image",
    "callback_url": "https://your-domain.com/webhook",
    "input": {"prompt": "..."}
}

Webhooks are more efficient than polling for production use. See Task Lifecycle for the full status flow.

File validity: generated images and videos are accessible for 24 hours after creation. Download and save your content promptly.

Rate limits: API rate limits vary by account type. Check your console dashboard for current limits.

Full example#

import requests
 
API_KEY = "your-api-key-here"
BASE_URL = "https://api.poyo.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}
 
response = requests.post(
    f"{BASE_URL}/api/generate/submit",
    json={
        "model": "gpt-4o-image",
        "callback_url": "https://your-domain.com/callback",
        "input": {"prompt": "A futuristic city", "size": "1:1"}
    },
    headers=headers
)
task_id = response.json()["data"]["task_id"]
 
status_response = requests.get(
    f"{BASE_URL}/api/generate/status/{task_id}",
    headers=headers
)
print(status_response.json())

Back to Documentation Index · Next: Error Codes

Updated Aug 14, 2026