Backend-safe AI generation examples for PoYo

Copy-paste backend workflows for PoYo image, video, music, 3D, and chat APIs.

Website | Docs | Models | Pricing | Dashboard | Discord

PoYo gives developers one account and one production workflow for multimodal generation: keep the API key on your server, submit a task, store data.task_id, poll while testing, and use webhooks in production.

Run Your First Task In 3 Minutes

The core path is the same for most media and 3D models:

POYO_API_KEY -> submit task -> data.task_id -> status polling or callback_url

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

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

Start with one of these:

# cURL quickstart
cat curl/image/gpt-image-2.md

# Node.js backend example
(cd node/gpt-image-2 && npm install && npm start)

# Python backend example
(cd python/gpt-image-2 && pip install -r requirements.txt && python main.py)

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

Cost And Failed Task Behavior

For generation APIs, the real cost is the cost of getting a usable result, not just sending a request.

PoYo uses credit-based pricing, and failed generation tasks are not charged credits. Your backend should still treat failed as a terminal state, log the reason, and retry only when it makes sense.

Start By Goal

Goal	Start here
Generate or edit images	curl/image/gpt-image-2.md, node/gpt-image-2/, python/gpt-image-2/
Generate short videos	curl/video/seedance-2.md, node/seedance-2/, python/seedance-2/
Try a high-interest video quickstart	curl/video/sora-2.md
Build chat completions	curl/chat/gpt-5.2.md, node/gpt-5.2/, python/gpt-5.2/
Keep API keys out of browser code	nextjs/gpt-image-2-route/
Receive production callbacks	webhooks/
Build from product recipes	recipes/
Understand shared task behavior	shared/README.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.

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.

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.