Build with PoYo

Welcome to PoYo.ai. 👋 This guide walks you through the essential information you need to start integrating PoYo.ai APIs into your product, including models, pricing, authentication, request flow, limits, and support. We aim to be transparent, practical, and developer-friendly. Please read this carefully before going to production. Access image, video, audio, music, 3D, and chat models through one API key. Start with a model call, then choose REST, CLI, or MCP for your application.

Browse models

Compare model capabilities and test inputs in the Playground.

Get an API key

Create a key and configure usage limits or an IP allowlist.

View pricing

Check current model pricing before submitting paid work.

1. Available Models & Playground

Find the latest supported models on our Model page.

We continuously update and onboard new models as soon as they are stable.
Each model page links to its Playground, where you can test and experiment directly in our UI before calling the API.
The Playground is the best place to understand model behavior, parameters, and output formats.

2. Pricing

The complete and up-to-date pricing list is available on the pricing page.

Our prices are typically 30%-50% lower than official APIs.
For some models, discounts can reach up to 80%.
Pricing may change as upstream providers adjust their costs, so always refer to the pricing page for the latest numbers.

3. Choose how to integrate

Approach	Best for
REST API	Product integrations in any language
PoYo CLI	Local testing, scripts, CI, and streaming chat
MCP	Letting Claude, Cursor, Codex, or VS Code discover and run models
Agent Skill	Teaching an agent the recommended discovery and execution workflow

4. Creating and Securing Your API Key

Create and manage your API keys on the API key page. Important security notes:

Never expose your API key in frontend code (browser, mobile apps, public repositories).
Treat your API key as a secret.

To help protect your usage, we provide:

Rate limits per key (hourly, daily, and total usage caps)
IP whitelist support, allowing only approved server IPs to access the API

These features help prevent accidental overuse and unauthorized requests.

5. Required Request Headers

Every API request must include the correct headers:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

If these headers are missing or incorrect, you may receive:

{"code":401,"error":{"message":"Invalid API key","type":"authentication_error"}}

Always double-check your headers when debugging authentication issues.

6. Make your first generation request

Generation is asynchronous. Submit a task, save its task_id, then poll its status or receive a webhook.

cURL
Python
JavaScript

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-image",
    "input": {
      "prompt": "A paper-cut illustration of a city at sunrise",
      "size": "1:1"
    }
  }'

import os
import requests

response = requests.post(
    "https://api.poyo.ai/api/generate/submit",
    headers={"Authorization": f"Bearer {os.environ['POYO_API_KEY']}"},
    json={
        "model": "gpt-4o-image",
        "input": {
            "prompt": "A paper-cut illustration of a city at sunrise",
            "size": "1:1",
        },
    },
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["task_id"]
print(task_id)

const response = await fetch("https://api.poyo.ai/api/generate/submit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o-image",
    input: {
      prompt: "A paper-cut illustration of a city at sunrise",
      size: "1:1",
    },
  }),
});

if (!response.ok) throw new Error(await response.text());
const { data } = await response.json();
console.log(data.task_id);

A successful submit response means the task was accepted, not that generation has finished.

7. Retrieve the result

curl "https://api.poyo.ai/api/generate/status/TASK_ID" \
  -H "Authorization: Bearer $POYO_API_KEY"

Continue while the task is queued or running. When it finishes, download the returned files to storage you control. For production workloads, prefer signed webhooks instead of frequent polling.

8. Logs & Task Details

Inspect all your historical tasks on the task history page. For each task, you can view:

Creation time
Model used
Input parameters
Task status
Credit consumption
Final results or error details

If you ever suspect incorrect credit usage, this page is the source of truth for verification.

9. Data Retention Policy

Please note our retention rules:

Generated media files: stored for 3 days, then automatically deleted
Log records (text / metadata): stored for 2 months, then automatically deleted

If you need long-term access, make sure to download and store results on your side in time.

10. Asynchronous Task Model

All generation tasks on PoYo.ai are asynchronous. A successful request returns:

HTTP 200
A task_id

A 200 response only means the task was created, not completed. To get the final result, you must either:

Provide a callback (webhook) URL in the request, or
Actively poll the “Get Task Status” API using the task_id

11. Rate Limits & Concurrency

By default, we apply the following limits:

Up to 20 new generation requests per 10 seconds
This typically allows 100+ concurrent running tasks
Limits are applied per account

If you exceed the limit:

Requests will be rejected with HTTP 429
Rejected requests will not enter the queue

For most users, this is more than sufficient. If you consistently hit 429 errors, you may contact support to request a higher limit - approvals are handled cautiously.

12. Before production

Keep API keys on your server; never expose them in browser or mobile code.
Validate inputs against the selected model’s current schema.
Handle 401, 402, 429, and transient server failures explicitly.
Treat every submission retry as potentially new paid work; confirm whether the original request created a task before resubmitting.
Review task statuses, error responses, and current pricing.
Generated media is temporary. Download results promptly and follow the retention policy shown in your account and API documentation.

13. Build with an AI assistant

Connect PoYo MCP when an assistant needs live model schemas, pricing, account information, and execution tools:

https://api.poyo.ai/mcp

Start with PoYo Integrations, or go directly to the setup guide for Claude, Cursor, Codex, or VS Code.

14. Support

Use the support entry in the PoYo dashboard for the fastest account-aware assistance, or email [email protected].

Developer Support

Recommended support channels are available directly from the dashboard’s bottom-left menu. Discord is the fastest option. What you get:

Private, 1-on-1 channels
Your data and conversations remain confidential
Faster and more technical responses

Support hours: UTC 21:00 - UTC 17:00 (next day). Email is available (slower): [email protected].

15. Stability Expectations

We provide access to top-tier, highly competitive APIs at very aggressive pricing. That said:

We are not perfect
Our overall stability may be slightly lower than official providers
This is a conscious trade-off

In practice, PoYo.ai is stable enough to support production workloads and long-term business growth, but we believe in setting realistic expectations upfront.

16. About the Team

PoYo.ai is built by a small startup team.

We move fast
We care deeply about developer experience
We are constantly improving

At the same time, we acknowledge that:

Not everything is perfect
We can’t satisfy every use case immediately

Your feedback helps us improve - and we genuinely appreciate it.

Overview

Image Model

Video Model

Music Model

Chat Model

3D Model

Task Management

Getting Started

Build with PoYo

Browse models

Get an API key

View pricing

1. Available Models & Playground

2. Pricing

3. Choose how to integrate

4. Creating and Securing Your API Key

5. Required Request Headers

6. Make your first generation request

7. Retrieve the result

8. Logs & Task Details

9. Data Retention Policy

10. Asynchronous Task Model

11. Rate Limits & Concurrency

12. Before production

13. Build with an AI assistant

14. Support

Developer Support

15. Stability Expectations

16. About the Team

​Build with PoYo

Browse models

Get an API key

View pricing

​1. Available Models & Playground

​2. Pricing

​3. Choose how to integrate

​4. Creating and Securing Your API Key

​5. Required Request Headers

​6. Make your first generation request

​7. Retrieve the result

​8. Logs & Task Details

​9. Data Retention Policy

​10. Asynchronous Task Model

​11. Rate Limits & Concurrency

​12. Before production

​13. Build with an AI assistant

​14. Support

​Developer Support

​15. Stability Expectations

​16. About the Team

Build with PoYo

1. Available Models & Playground

2. Pricing

3. Choose how to integrate

4. Creating and Securing Your API Key

5. Required Request Headers

6. Make your first generation request

7. Retrieve the result

8. Logs & Task Details

9. Data Retention Policy

10. Asynchronous Task Model

11. Rate Limits & Concurrency

12. Before production

13. Build with an AI assistant

14. Support

Developer Support

15. Stability Expectations

16. About the Team