PoYo AI API Documentation

PoYo AI provides state-of-the-art image and video generation APIs with a unified, asynchronous architecture.

Base URL

All API requests should be made to:

https://api.poyo.ai

Authentication

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

Authorization: Bearer YOUR_API_KEY

Get Your API Key

Visit the API Console to generate your API key

API Architecture

Unified Endpoints

PoYo AI uses a simple two-endpoint architecture for all generation types:

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.

Asynchronous Processing

All generation tasks follow this workflow:

Submit Task

POST to /api/generate/submit with model and parameters

Receive Task ID

API returns task_id immediately with status not_started

Poll or Wait

Either poll /api/generate/status/{task_id} or receive webhook callback

Retrieve Results

When status is finished, get generated files from response

Response Format

All endpoints return JSON with a consistent structure:

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
  }
}

Task Status Values

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"
  }
}

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

Task Management Options

Option 1: Polling (Simple)

Poll the status endpoint periodically:

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)

Option 2: Webhooks (Recommended)

Provide a callback_url to receive automatic notifications:

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

Webhook Documentation

Learn how to implement webhook callbacks

Important Notes

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.

Callbacks vs Polling: Webhooks are more efficient than polling and recommended for production use.

Quick Example

import requests

API_KEY = "your-api-key-here"
BASE_URL = "https://api.poyo.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Submit task
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"]

# Check status
status_response = requests.get(
    f"{BASE_URL}/api/generate/status/{task_id}",
    headers=headers
)
print(status_response.json())

Overview

Image Model

Video Model

Music Model

Chat Model

3D Model

Task Management

API Overview

PoYo AI API Documentation

Base URL

Authentication

Get Your API Key

API Architecture

Unified Endpoints

Submit Task

Query Status

Asynchronous Processing

Response Format

Submit Response

Status Response

Task Status Values

Error Response

HTTP Status Codes

Task Management Options

Option 1: Polling (Simple)

Option 2: Webhooks (Recommended)

Webhook Documentation

Important Notes

Quick Example

​PoYo AI API Documentation

​Base URL

​Authentication

Get Your API Key

​API Architecture

​Unified Endpoints

​Submit Task

​Query Status

​Asynchronous Processing

​Response Format

​Submit Response

​Status Response

​Task Status Values

​Error Response

​HTTP Status Codes

​Task Management Options

​Option 1: Polling (Simple)

​Option 2: Webhooks (Recommended)

Webhook Documentation

​Important Notes

​Quick Example

PoYo AI API Documentation

Base URL

Authentication

API Architecture

Unified Endpoints

Submit Task

Query Status

Asynchronous Processing

Response Format

Submit Response

Status Response

Task Status Values

Error Response

HTTP Status Codes

Task Management Options

Option 1: Polling (Simple)

Option 2: Webhooks (Recommended)

Important Notes

Quick Example