Skip to main content

​
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:
1

Submit Task

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

Receive Task ID

API returns task_id immediately with status not_started
3

Poll or Wait

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

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

StatusDescription
not_startedTask queued, waiting to begin
runningTask currently processing
finishedTask completed, results available in files array
failedTask failed, error details in error_message

​
Error Response

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

​
HTTP Status Codes

CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
402Payment Required - Insufficient account balance
500Internal 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)
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())