Kling 4.0 API 已上线，立即体验视频生成 →
PoYoPoYo
tutorials

Seedream 5.0 Pro API 指南：使用代码生成和编辑图像

Poyo.ai Team
3 min read
Share:

Seedream 5.0 Pro API 使用指南

Seedream 5.0 Pro API 为开发者提供了通过面向生产环境的异步工作流调用 ByteDance 旗舰图像生成与编辑模型的能力。本指南将介绍如何通过 Poyo.ai 提交文生图和图像编辑任务，并通过轮询或 Webhook 获取最终结果。

目前，无论使用哪种模型变体，每张生成的图像均为 15 credits，约合 $0.075。

API 模型与参数

工作流模型 ID
文生图seedream-5.0-pro
图像编辑seedream-5.0-pro-edit

支持的输入参数包括：

  • prompt：必填，生成或编辑指令
  • size：分辨率预设（如 1K、2K），或宽高比（如 1:1、4:3、3:4、16:9、9:16）
  • n：生成图片数量
  • output_format：jpeg 或 png
  • image_urls：编辑模型使用的参考图片，最多支持 10 张
  • callback_url：可选，用于接收完成通知的 HTTPS 回调地址

最新接口定义请参阅实时 API 文档。

1. 创建 API Key

创建一个 Poyo.ai 账号，打开 API Key Management，并将密钥保存到环境变量中。切勿在浏览器代码中暴露生产环境密钥，也不要将其提交到 Git 仓库。

export POYO_API_KEY="your-api-key"

2. 提交文生图请求

所有任务均使用统一提交接口：

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

返回结果中包含任务 ID：

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

3. 使用 JavaScript 调用 Seedream 5.0 Pro

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;
}

当图像分辨率比固定宽高比更重要时，建议使用 2K。如果输出需要适配特定版式，则建议使用宽高比参数。

4. 使用 Python 调用 Seedream 5.0 Pro

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. 使用多张参考图进行图像编辑

切换模型 ID，并提供 image_urls。在提示词中明确说明每张参考图的用途。

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

为了获得更稳定的编辑效果，建议将提示词分为三个部分：参考图角色、需要修改的内容，以及需要保留的约束条件。

6. 获取结果

提交任务采用异步方式。收到 task_id 后，可以选择以下任一方式获取结果：

  • 轮询 Poyo.ai 的统一任务状态接口；或
  • 提供 callback_url，通过完成后的 Webhook 接收结果。

当前任务状态接口及返回对象请参考任务管理文档。在生产环境中，建议使用指数退避（Exponential Backoff）策略，而不是持续高频轮询。

错误处理

建议针对以下情况进行明确处理：

  • 400：模型参数无效、不支持的尺寸、无法访问的图片 URL，或 JSON 格式错误
  • 401：API Key 缺失或无效
  • 异步任务失败：提交成功后，生成过程执行失败
  • Webhook 重试：同一个完成事件可能会被重复推送

建议将任务 ID 与系统内部任务 ID 建立映射；Webhook 处理应具备幂等性；记录服务提供方返回的错误信息时，不要记录任何密钥等敏感数据。

生产环境检查清单

  • API Key 仅保存在服务端。
  • 提交前校验提示词长度和图片 URL 类型。
  • 使用生成服务可访问的 HTTPS 参考图片。
  • 为提交请求设置超时时间。
  • 对临时网络错误进行重试，但不要盲目重试无效请求。
  • 按照当前价格，以 请求输出数量 × 15 credits 跟踪成本。
  • 发布前检查生成的文本、产品信息及事实性内容。
  • 根据产品和目标市场，增加适当的内容审核机制。

什么时候选择 Pro 而不是 Lite

对于结构化设计、复杂排版、多语言文本以及需要精细控制的图像编辑，推荐使用 Seedream 5.0 Pro。如果追求更低成本、更高吞吐量，且不需要 Pro 级设计精度，则推荐使用 Seedream 5.0 Lite。

如果想了解非技术层面的介绍，请阅读Seedream 5.0 Pro 功能与价格。你也可以在 Seedream 5.0 Pro 模型页面 通过可视化界面测试 API 请求参数。

常见问题

Seedream 5.0 Pro API 的接口地址是什么？

生成和编辑任务均通过 POST https://api.poyo.ai/api/generate/submit 提交。

图像编辑模型的 ID 是什么？

使用 seedream-5.0-pro-edit，并在 input.image_urls 中提供一张或多张参考图片。

最多支持多少张参考图片？

根据当前 Poyo.ai 文档，Seedream 5.0 Pro 图像编辑最多支持 10 张参考图片。

每张 API 生成图片的费用是多少？

目前 Poyo.ai 的价格为每张生成或编辑图片 15 credits，约合 $0.075。

Share: