PoYo Examples

Production workflows for building image, video, music, 3D, and chat products with PoYo AI APIs.

Website | Docs | Models | Pricing | Dashboard | Discord

PoYo gives developers one account and one API workflow for multimodal generation. This repo is designed for backend builders: submit tasks from a server, store task IDs, poll or receive webhooks, then download generated files before they expire.

Repository Status

• Latest release: v0.1.0.
• Changelog: CHANGELOG.md.
• Local checks: make check or pwsh -NoLogo -NoProfile -File scripts/check.ps1; on Windows PowerShell, use powershell -NoLogo -NoProfile -File scripts/check.ps1.
• Contributions: CONTRIBUTING.md.
• Security reports: SECURITY.md.
• Issues: choose a template, bug report, or example request.

Start In 3 Minutes

1. Create an account at poyo.ai.
2. Create an API key in API Keys.
3. Copy .env.example to .env.
4. Set POYO_API_KEY.
5. Run one cURL, Node.js, or Python example.
6. Store the returned data.task_id.
7. Poll status or provide callback_url for webhooks.

cp .env.example .env
export POYO_API_KEY="your-api-key"
export POYO_BASE_URL="https://api.poyo.ai"

Never expose a PoYo API key in browser code, mobile apps, public repositories, screenshots, or client-side logs.

Choose Your Workflow

Goal	Start here
Test a model with cURL	curl/
Build a Node.js backend	node/
Build a Python backend	python/
Add a Next.js server route	nextjs/
Start from product recipes	recipes/
Receive production callbacks	webhooks/
Troubleshoot shared behavior	shared/README.md
Promote demos on social channels	social/first-batch.md

First Batch Examples

Model	Capability	Example
gpt-image-2	Product image generation and editing	curl/image/gpt-image-2.md
seedance-2	Short social video generation	curl/video/seedance-2.md
sora-2	High-interest video quickstart	curl/video/sora-2.md
generate-music	Background music generation	curl/music/generate-music.md
meshy-6-text-to-3d	Prompt to downloadable 3D asset	curl/3d/meshy-6-text-to-3d.md
gpt-5.2	OpenAI-style chat completion	curl/chat/gpt-5.2.md

Examples Index

Model	Modality	Workflow	cURL	Node.js	Python	Next.js	Webhook	Sample Output
gpt-image-2	Image	Async task	cURL	Node.js	Python	Route	Receivers	PoYo model page sample
seedance-2	Video	Async task	cURL	Node.js	Python	-	Receivers	PoYo model page sample
sora-2	Video	Async task	cURL	-	-	-	Receivers	PoYo model page sample
generate-music	Music	Async task	cURL	-	-	-	Receivers	PoYo model page sample
meshy-6-text-to-3d	3D	Async task	cURL	-	-	-	Receivers	PoYo model page sample
gpt-5.2	Chat	Sync response	cURL	Node.js	Python	-	-	Chat docs

Model-Specific Repositories

Use this repo as the main integration hub. If you are searching for a single model, these focused repos provide smaller entry points with cURL, Node.js, webhook, prompt, and production notes.

Category	Model repo	Best for
Image	PoyoAPI/gpt-image-2-api	GPT Image 2 generation and editing
Image	PoyoAPI/nano-banana-2-api	Nano Banana 2 generation and image edits
Image	PoyoAPI/nano-banana-pro-api	Nano Banana Pro higher-detail image workflows
Video	PoyoAPI/seedance-2-api	Seedance 2 video generation and fast drafts
Video	PoyoAPI/sora-2-official-api	Sora 2 Official video and reference-frame workflows
Video	PoyoAPI/happy-horse-api	Happy Horse text-to-video and image-to-video workflows

Unified Async Flow

Most media and 3D examples use the same backend pattern.

POST https://api.poyo.ai/api/generate/submit
Authorization: Bearer <POYO_API_KEY>
Content-Type: application/json

The submit response returns a task ID:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-05-19T08:00:00"
  }
}

Persist data.task_id, then poll:

GET https://api.poyo.ai/api/generate/status/{task_id}
Authorization: Bearer <POYO_API_KEY>

Or pass callback_url during submit and process the webhook when the task reaches finished or failed.

Chat examples use the synchronous OpenAI-style endpoint:

POST https://api.poyo.ai/v1/chat/completions
Authorization: Bearer <POYO_API_KEY>
Content-Type: application/json

Production Checklist

• Keep POYO_API_KEY server-side only.
• Store data.task_id before polling or waiting for webhooks.
• Treat finished and failed as terminal states.
• Use moderate polling intervals and backoff on transient errors.
• Make webhook handlers idempotent.
• Only process webhook task IDs your system submitted.
• Download and store generated files before they expire.
• Check Dashboard History when debugging task cost, status, and output.

Contributing

Issues and PRs are welcome. Keep examples small, backend-safe, and runnable with minimal dependencies. See CONTRIBUTING.md before adding examples, and use SECURITY.md for sensitive reports.