PoYo AI API Documentation

PoYo AI provides image, video, LLM, 3D, and music APIs behind one API key.

Model Categories

Generation models (image, video, 3D, music) run as asynchronous tasks. LLMs answer directly in the HTTP response or as a stream.

Category	Request	Result	Overview
Image	`POST /api/generate/submit`	Image task status or webhook	Image Models
Video	`POST /api/generate/submit`	Video task status or webhook	Video Models
3D	`POST /api/generate/submit`	3D task status or webhook	3D Models
Music (Suno)	`POST /api/generate/submit`	Query Music Detail or webhook	Music & Audio Models
Music & TTS (other providers)	`POST /api/generate/submit`	Task status or webhook	Music & Audio Models
AI Tools	`POST /api/generate/submit`	Task status or webhook	AI Tools
LLM	`/v1/chat/completions`, `/v1/responses`, `/v1/messages`, or Gemini Native	Returned in the response or streamed	LLM Models

The rest of this page describes the asynchronous task flow used by generation models.

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

Image, video, 3D, and most audio models use two endpoints:

Submit Task

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

Submit a generation request. 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 3 days 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

Task Management

File Management

Account Management

Security & Best Practices

API Overview

PoYo AI API Documentation

Model Categories

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

​Model Categories

​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

Model Categories

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