Skip to main content

Build with PoYo

Access image, video, audio, music, 3D, and chat models through one API key. Start with a model call, then choose REST, CLI, MCP, or an Agent Skill for your application.
Welcome to PoYo.ai. 👋 This guide covers models, authentication, request flow, limits, and support. We aim to be transparent, practical, and developer-friendly. Please read it before going to production.

Get an API key

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

Make your first request

Submit a task with cURL, Python, or JavaScript.

Use it from an AI agent

Generate from Claude Code, Codex, or Cursor in three steps.

Browse models & pricing

Compare capabilities, test in the Playground, and check prices.

1. Available Models & Playground

Each model category has an overview listing every model, its model IDs, and how to get results:

Image

Text-to-image and image editing.

Video

Text, image, and reference to video.

LLM

GPT, Claude, Gemini, DeepSeek, Grok, and Kimi.

3D

Text and image to 3D meshes.

Music & Audio

Suno music, TTS, and audio tools.

AI Tools

Translation, upscaling, background removal, and moderation.
Find the latest supported models, prices, and Playgrounds 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. Choose how to integrate

REST API

Product integrations in any language.

PoYo CLI

Local testing, scripts, CI, and streaming chat.

MCP

Let Claude, Cursor, Codex, or VS Code discover and run models.

Agent Skill

Teach an agent the recommended discovery and execution workflow.

3. Creating and Securing Your API Key

Create and manage your API keys on the API key page.
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.

4. Required Request Headers

Every API request must include the correct headers:
Anthropic Messages (/v1/messages) also accepts x-api-key: <YOUR_API_KEY>, so the official Anthropic SDKs work without changes.
Always double-check your headers when debugging authentication issues.

5. Make your first generation request

Generation is asynchronous. Submit a task, save its task_id, then poll its status or receive a webhook.
A successful submit response means the task was accepted, not that generation has finished.

6. Retrieve the result

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.

7. 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
  • Final results or error details

8. Data Retention Policy

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

9. Asynchronous Task Model

All generation tasks on PoYo.ai are asynchronous. A successful request returns HTTP 200 and a task_id. A 200 response only means the task was created, not completed.
1

Submit

Send the generation request and save the returned task_id.
2

Wait for the result

Either provide a callback (webhook) URL in the request, or actively poll the “Get Task Status” API using the task_id.
3

Store the output

Download the finished files before the retention window ends.

10. Rate Limits & Concurrency

This limit applies to generation tasks submitted to /api/generate/submit. LLM endpoints are currently not rate limited. If you exceed the limit, requests are rejected with HTTP 429 and do 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.

11. 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.
Generated media is temporary. Download results promptly and follow the retention policy shown in your account and API documentation.

12. Build with an AI assistant

Use PoYo from coding agents such as Claude Code, Codex, and Cursor. The fastest path needs no MCP setup; see the Quickstart. Connect PoYo MCP when an assistant needs live model schemas, account information, and execution tools:

Claude

Cursor

Codex

VS Code

See AI Agents for all options.

13. Support

Use the support entry in the PoYo dashboard for the fastest account-aware assistance. Recommended support channels are available directly from the dashboard’s bottom-left menu.

Developer Support

Discord (fastest)

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

Email (slower)

Support hours: UTC 01:00 - UTC 10:00 (09:00 - 18:00 Beijing time, UTC+8).

14. Stability Expectations

We provide access to top-tier, highly competitive APIs. That said, we are not perfect, and 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.

15. About the Team

PoYo.ai is built by a small startup team. We move fast, we care deeply about developer experience, and we are constantly improving. At the same time, we acknowledge that not everything is perfect, and we can’t satisfy every use case immediately. Your feedback helps us improve, and we genuinely appreciate it.