Seedream 5.0 Pro API Guide: Generate and Edit Images with Code

Seedream 5.0 Pro API guide

The Seedream 5.0 Pro API gives developers access to ByteDance's flagship image generation and editing model through a production-oriented asynchronous workflow. This guide shows how to submit text-to-image and image-editing jobs through Poyo.ai, then retrieve the result with polling or a webhook.

The current price is 15 credits, about $0.075 per generated image, for both model variants.

API Models and Parameters

Workflow	Model ID
Text to image	`seedream-5.0-pro`
Image editing	`seedream-5.0-pro-edit`

Supported inputs include:

prompt: required generation or editing instruction
size: a resolution preset such as 1K or 2K, or an aspect ratio such as 1:1, 4:3, 3:4, 16:9, or 9:16
n: number of images to generate
output_format: jpeg or png
image_urls: reference images for the edit model, up to 10
callback_url: optional HTTPS endpoint for completion notifications

See the live API reference for the current schema.

1. Create an API Key

Create a Poyo.ai account, open API Key Management, and store the key in an environment variable. Never expose a production key in browser code or commit it to Git.

export POYO_API_KEY="your-api-key"

2. Submit a Text-to-Image Request

All jobs use the unified submit endpoint:

POST https://api.poyo.ai/api/generate/submit

cURL

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro",
    "callback_url": "https://example.com/webhooks/poyo",
    "input": {
      "prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
      "size": "3:4",
      "n": 1,
      "output_format": "png"
    }
  }'

The response contains a task ID:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. Call Seedream 5.0 Pro with JavaScript

const API_URL = 'https://api.poyo.ai/api/generate/submit';

async function generateSeedreamImage(prompt) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POYO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'seedream-5.0-pro',
      input: {
        prompt,
        size: '2K',
        n: 1,
        output_format: 'png',
      },
    }),
  });

  const payload = await response.json();
  if (!response.ok || payload.code !== 200) {
    throw new Error(payload.error?.message || 'Seedream request failed');
  }
  return payload.data.task_id;
}

Use 2K when resolution matters more than a fixed ratio. Use an aspect-ratio value when the placement format is the primary constraint.

4. Call Seedream 5.0 Pro with Python

import os
import requests

API_URL = "https://api.poyo.ai/api/generate/submit"

def generate_seedream_image(prompt: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "seedream-5.0-pro",
            "input": {
                "prompt": prompt,
                "size": "16:9",
                "n": 1,
                "output_format": "jpeg",
            },
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
    return payload["data"]["task_id"]

5. Edit Images with Multiple References

Switch the model ID and provide image_urls. Tell the model what each reference contributes.

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro-edit",
    "input": {
      "prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
      "image_urls": [
        "https://example.com/room.jpg",
        "https://example.com/chair.png",
        "https://example.com/logo.png"
      ],
      "size": "16:9",
      "n": 1,
      "output_format": "png"
    }
  }'

For reliable edits, separate the prompt into three ideas: reference roles, requested changes, and preservation constraints.

6. Retrieve the Result

Submission is asynchronous. After receiving task_id, either:

poll Poyo.ai's unified task-status endpoint; or
provide callback_url and process the completion webhook.

Follow the task management documentation for the current status route and response object. In production, use exponential backoff rather than polling continuously.

Error Handling

Handle these cases explicitly:

400: invalid model parameters, unsupported sizes, inaccessible image URLs, or malformed JSON
401: missing or invalid API key
failed async task: generation failed after a valid submission
webhook retry: the same completion event may be delivered more than once

Store the task ID with your internal job ID, make webhook handling idempotent, and log provider error messages without logging secrets.

Production Checklist

Keep API keys server-side.
Validate prompt length and image URL types before submission.
Use HTTPS reference images that the generation service can access.
Set request timeouts for submission calls.
Retry transient network errors, but do not blindly retry invalid requests.
Track cost as number of requested outputs × 15 credits at current pricing.
Review generated text, product details, and factual claims before publishing.
Add content moderation appropriate to your product and market.

When to Use Pro Instead of Lite

Use Seedream 5.0 Pro for structured designs, dense layouts, multilingual text, and controlled edits. Use Seedream 5.0 Lite for lower-cost, higher-volume image jobs where Pro-level design precision is not necessary.

For a non-technical overview, read Seedream 5.0 Pro features and pricing. You can also test the API payload visually on the Seedream 5.0 Pro model page.

Frequently Asked Questions

What is the Seedream 5.0 Pro API endpoint?

Submit generation and editing jobs to POST https://api.poyo.ai/api/generate/submit.

What is the edit model ID?

Use seedream-5.0-pro-edit and include one or more values in input.image_urls.

How many reference images are supported?

The current Poyo.ai documentation supports up to 10 reference images for Seedream 5.0 Pro editing.

How much does one API image cost?

The current Poyo.ai price is 15 credits, about $0.075, for each generated or edited image.