GPT Image 2 API Examples for PoYo

Focused server-side examples for building with gpt-image-2 and gpt-image-2-edit on PoYo.

The API workflow is: submit a task from your server, store data.task_id, poll in testing, and use callback_url webhooks in production.

Model Page | Docs | Get API Key | Pricing | Main Examples

GPT Image 2 is useful when an image task needs more than a loose concept: product shots, ad visuals, UI mockups, social thumbnails, readable text, or controlled edits from a reference image.

Sample output: PoYo model page sample.

This is an official PoYo model page sample, not a file generated by this repo.

What This Repo Covers

• Text-to-image with gpt-image-2
• Image editing with gpt-image-2-edit
• cURL, Node.js, Python, and Next.js server route examples
• Async task flow: submit, store data.task_id, poll status, retrieve files
• Webhook receiver notes for production callbacks
• Prompt examples and production integration notes

Quick Start

cp .env.example .env
export POYO_API_KEY="your-api-key"

Run the Node.js example:

cd node
npm start

Or run the Python example:

cd python
pip install -r requirements.txt
python main.py

Keep POYO_API_KEY on the server. Do not expose it in browser code, mobile apps, screenshots, or public logs.

API Flow

Submit an image task:

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

Store the returned data.task_id, then poll:

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

For production queues, pass callback_url during submit and use a webhook receiver for terminal task updates.

Text To Image

{
  "model": "gpt-image-2",
  "input": {
    "prompt": "A premium product photo of a matte black smart speaker on a clean white studio background, realistic softbox lighting, high detail",
    "quality": "low",
    "size": "1:1",
    "resolution": "1K"
  }
}

Image Edit

Use gpt-image-2-edit when the request includes a reference image.

{
  "model": "gpt-image-2-edit",
  "callback_url": "https://example.com/api/poyo/webhook",
  "input": {
    "prompt": "Replace the background with a clean studio backdrop and add a soft natural shadow",
    "quality": "high",
    "size": "1:1",
    "resolution": "2K",
    "image_urls": [
      "https://example.com/source-product.png"
    ]
  }
}

Examples

Path	What it covers
curl/generate.md	Copy-paste submit and status requests.
node/	Native Node.js submit and poll flow.
python/	Python submit and poll flow with requests.
nextjs/	Next.js route handlers that keep the API key server-side.
webhooks/express-webhook/	Minimal Express receiver for PoYo callbacks.
docs/prompt-examples.md	Practical prompts for product, UI, ads, and edits.
docs/production-notes.md	Security and reliability notes before launch.

Expected Submit Response

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

Expected Status Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "finished",
    "progress": 100,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/image.png",
        "file_type": "image"
      }
    ],
    "error_message": null
  }
}

Production Checklist

• Keep POYO_API_KEY server-side only.
• Validate prompts and reference image URLs before submit.
• Store data.task_id before polling or waiting for webhooks.
• Treat finished and failed as terminal states.
• Log task IDs and status transitions, not API keys or private prompts.
• Make webhook handlers idempotent.
• Download returned image files before they expire.
• Check current model availability and cost on the PoYo model page.

Run Checks

make check

On Windows:

./scripts/check.ps1

License

MIT