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.
- 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. 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
4. Required Request Headers
Every API request must include the correct headers:/v1/messages) also accepts x-api-key: <YOUR_API_KEY>, so the official Anthropic SDKs work without changes.
What a missing or invalid key returns
What a missing or invalid key returns
5. Make your first generation request
Generation is asynchronous. Submit a task, save itstask_id, then poll its status or receive a webhook.
- cURL
- Python
- JavaScript
A successful submit response means the task was accepted, not that generation has finished.
6. Retrieve the result
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
9. Asynchronous Task Model
All generation tasks on PoYo.ai are asynchronous. A successful request returns HTTP 200 and atask_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.
Review task statuses and error responses.
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
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.