Make Your First Generation Request

Before you start#

• 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 from the dashboard.
• Check pricing — review current model pricing before submitting paid work on the pricing page.

Choose how to integrate#

Submit a generation request#

Generation runs asynchronously. Submit a task, save its task_id, then poll its status or receive a webhook.

cURL:

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"
    }
  }'

Python:

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)

JavaScript:

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.

Retrieve the result#

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

Continue polling 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.

Checklist 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.
• Use an idempotency key when the endpoint supports it so retries do not duplicate paid work.
• 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.

Connect an AI assistant instead#

Give Claude, Cursor, Codex, or VS Code live access to PoYo model discovery, schemas, and execution through MCP:

https://api.poyo.ai/mcp

Start with the Integrations Overview, or go straight to Connect with MCP.

Get support#

Reach the PoYo team through the dashboard or by emailing support@poyo.ai.

Back to Documentation Index