APIMart
APIMart

如何使用 Seedream 5.0 Pro 生成图像

手把手教你在 APIMart 调用 Seedream 5.0 Pro:认证、请求字段、任务轮询、读取结果,以及在链接过期前保存图片。

教程

跑通 Seedream 5.0 Pro 只需要一次 POST 请求、一个 API Key 和一个后续步骤:提交任务,拿到 task_id,再查询任务直到图片生成完成。Seedream 5.0 Pro 是异步模型,第一次响应里不会直接返回图片。

简要版本:

  • 请求地址是 https://api.apimart.ai/v1/images/generations
  • 请求头加上 Authorization: Bearer YOUR_API_KEY
  • model 设为 seedream-5-0-pro
  • 传入 prompt,再加上 resolution(1K、1.5K 或 2K)和 size(auto 或 16:9 这类比例)
  • 需要编辑或合成图片时,在 image_urls 里放最多 10 张参考图
  • 每 5–10 秒轮询一次 GET /v1/tasks/{task_id},直到状态变为 completed
  • 立即下载结果,因为图片链接的有效期是 72 小时

最需要记住的一点:这是单图模型。每次请求只返回一张图,n 大于 1 会被拒绝。你可以在 APIMart 上试用 Seedream 5.0 Pro API,完整字段说明见 API 文档。

APIMart
Seedream 5.0 Pro API:请求与轮询速查表

核心要点

  • 调用 Seedream 5.0 Pro 时,向 https://api.apimart.ai/v1/images/generations 发送 POST 请求,请求头为 Authorization: Bearer YOUR_API_KEY,model 设为 seedream-5-0-pro。
  • 用 resolution(1K、1.5K 或 2K)选择输出档位,用 size 选择形状:auto、十种比例之一或精确像素。1.5K 与 1K 同价;3K 和 4K 会返回 400。
  • 每次请求只生成一张图。n 大于 1、组图、流式输出和联网搜索都会被 400 拒绝,且不会创建任务。
  • 图像编辑通过 image_urls 传入最多 10 张参考图,支持公网 URL 或 Base64 Data URI。
  • 第一次响应只包含 task_id。每 5–10 秒轮询一次任务接口,并在 72 小时内保存图片。

快速对比

项目适用场景关键限制或说明
文生图只用提示词生成新图不需要输入图片
单图编辑修改一张图的背景、光线或细节image_urls 中放 1 张
多参考图编辑合成人物、服装或场景最多 10 张参考图
图层拆分把海报拆成可编辑图层必须且只能输入 1 张图,最多 16 个 PNG 图层
透明背景编辑图层并保留透明通道输入 1 张带 alpha 的图,output_format: "png"

一句话总结:本文介绍如何设置认证、构建请求体、轮询任务并保存结果,避免丢失文件。

1. 设置 API 访问与认证

1.1 创建你的 APIMart 账户并生成 API Key

APIMart

在 APIMart 注册账户,打开控制台里的 API Key 管理页面,创建一个 Key。创建后立即复制,并保存在服务端的密钥管理服务或环境变量中。

不要把 Key 写进前端代码或公开仓库,任何拿到它的人都可以消耗你的余额。在 Node.js 中通过 process.env.APIMART_API_KEY 读取;在 shell 中使用 export APIMART_API_KEY="your-key-here"。

1.2 设置 Base URL 与 Bearer 认证头

所有请求都发往 https://api.apimart.ai,并带上两个请求头:

请求头值
AuthorizationBearer YOUR_API_KEY
Content-Typeapplication/json

Bearer 前缀后面保留且只保留一个空格。缺少 Token 或格式错误会返回 401。如果 cURL 能跑通而你的应用不行,问题通常出在应用拼接请求头的方式上。

2. 构建 Seedream 5.0 Pro 图像请求

APIMart

2.1 核心字段:Model、Prompt、Resolution 和 Size

文生图请求需要 model 和 prompt,另外两个字段控制输出:

  • model:seedream-5-0-pro(也接受 seedream-5.0-pro)。
  • prompt:自然语言描述。除中文和英文外,模型还能原生渲染日语、韩语、西班牙语、葡萄牙语、法语、德语、俄语、印尼语、越南语等多种语言的文字。建议控制在约 600 个英文单词以内,过长的描述可能丢失细节。
  • resolution:1K(默认)、1.5K 或 2K。1.5K 与 1K 同价,通常是更好的选择。
  • size:auto(默认)、十种比例之一(1:1、4:3、3:4、16:9、9:16、3:2、2:3、2:1、1:2、21:9),或 2048x1024 这样的精确像素。精确像素的总像素数须在 921,600 到 4,624,220 之间,宽高比在 1:16 到 16:1 之间。

例如 resolution: "1.5K" 配合 size: "16:9" 会输出 2048×1152 的图片。

2.2 可选字段

可选参数类型使用场景
image_urlsArray图像编辑与多参考图合成;最多 10 个公网 URL 或 Base64 Data URI
output_formatStringjpeg(默认)或 png
backgroundString编辑一张本身带 alpha 通道的图时设为 transparent 以保留透明(需 png)
layer_decompositionBoolean把一张图拆成一张底图和最多 16 个透明 PNG 图层
optimize_prompt_optionsObject提示词优化,仅支持 {"mode": "standard"}
watermarkBoolean在右下角添加“AI 生成”标识
nsfw_checkBoolean提交任务前审核提示词和输入图片

每张参考图支持 jpeg、png、webp、bmp、tiff、gif、heic、heif,单张不超过 30 MB、3,600 万像素。第一张参考图免费,之后每多一张收取固定附加费。

如需精确指定编辑位置,可在提示词里写坐标:单点用 <point>x y</point>,区域用 <bbox>x1 y1 x2 y2</bbox>。

2.3 本模型会拒绝的字段

Seedream 5.0 Pro 是单图模型。以下请求会返回 400,不创建任务,也不扣费:

  • n 大于 1,或使用 sequential_image_generation(组图请使用 Seedream 5.0 Lite)
  • stream 或 tools(不支持流式输出和联网搜索)
  • image_urls 超过 10 张
  • 3K、4K 等不支持的档位,或不在上述列表中的比例

2.4 cURL 与 JavaScript 示例调用

下面是一个最小的 cURL 请求,生成一张 1.5K 档的 16:9 图片:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "resolution": "1.5K",
    "size": "16:9"
  }'

响应只确认任务已提交:

{
  "code": 200,
  "data": [{ "status": "submitted", "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K" }]
}

下面是用 Node.js fetch 做多参考图编辑:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedream-5-0-pro",
    prompt: "Replace the outfit in image 1 with the outfit in image 2",
    image_urls: ["https://example.com/person.jpg", "https://example.com/dress.jpg"],
    resolution: "2K",
    size: "auto",
  }),
});

const { data } = await response.json();
const taskId = data[0].task_id;

这些调用都放在服务端,不要放进客户端代码。

3. 轮询任务并保存图片

3.1 查询任务状态

带上同样的 Authorization 请求头,发送 GET https://api.apimart.ai/v1/tasks/{task_id}。Seedream 5.0 Pro 以质量优先,一个任务可能需要几分钟。建议每 5–10 秒轮询一次,客户端超时设为约 5 分钟。

当 status 变为 completed 或 failed 时停止轮询。失败的任务会全额退款。

3.2 读取结果

完成的任务如下:

{
  "code": 200,
  "data": {
    "id": "task_01JFXYZ123456789ABCDEF",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
          "expires_at": 1784696685
        }
      ]
    }
  }
}

从 data.result.images[0].url[0] 读取图片地址,响应里还会包含任务的 cost。链接有效期为 72 小时(expires_at 是 Unix 时间戳),请下载文件并转存到自己的存储,不要只保存 URL。

3.3 Python 完整示例

import os
import time

import requests

BASE_URL = "https://api.apimart.ai"
headers = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-pro",
        "prompt": "A product poster with the headline SUMMER SALE in bold letters",
        "resolution": "1.5K",
        "size": "3:4",
        "output_format": "png",
    },
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"][0]["task_id"]

while True:
    task = requests.get(f"{BASE_URL}/v1/tasks/{task_id}", headers=headers, timeout=30).json()["data"]
    if task["status"] == "completed":
        image_url = task["result"]["images"][0]["url"][0]
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", {}).get("message", task["status"]))
    time.sleep(5)

with open("seedream-5-0-pro.png", "wb") as f:
    f.write(requests.get(image_url, timeout=60).content)

4. 三种常见的图像工作流

  • 带文字的海报和图形。把要出现的文字用引号写进提示词,描述版式(例如“竖版海报,标题在顶部”),使用 resolution: "1.5K" 并固定比例,如 3:4。只在最终成品时切换到 2K,因为 2K 档价格更高。

  • 多参考图编辑。把人物、商品或场景图放进 image_urls,在提示词里按顺序称呼它们(“图 1”“图 2”)。使用 size: "auto" 时,输出比例会跟随参考图。也可以加 <bbox> 坐标,精确指定内容放在哪里。

  • 图层拆分与透明编辑。发送一张 PNG 或 JPEG 并设置 layer_decomposition: true,可得到一张底图和最多 16 个带位置与层级信息的透明 PNG 图层。要单独编辑某个图层,把该图层回传,并设置 background: "transparent" 和 output_format: "png"。图层任务先预授权,完成后按实际输出张数结算,多扣部分自动退回。

5. 可靠接入 Seedream 5.0 Pro 的检查清单

认证与密钥安全。把 Key 放在环境变量或密钥管理服务中,只从后端调用 API。

发送前校验参数。使用 seedream-5-0-pro,不传 n(或设为 1),image_urls 不超过 10 张,只使用 1K、1.5K 或 2K 并搭配支持的 size。

按异步流程设计。每 5–10 秒轮询一次,客户端超时设为约 5 分钟,并处理 failed 状态。

及时转存结果。任务成功后立即下载每张图片,链接会在 72 小时后失效。

扩量前先核对费用。输出按像素档位逐张计费(1K 与 1.5K 同为较低价格,2K 更高),第一张之后的每张参考图另收附加费。批量运行前请先查看实时价格表。

常见问题

拿到 task_id 之后,我怎么查询图像任务?

带上 Authorization: Bearer 请求头,发送 GET https://api.apimart.ai/v1/tasks/{task_id}。

每 5–10 秒轮询一次,直到 status 变为 completed,再从 data.result.images[0].url[0] 读取图片。如果状态是 failed,查看 error 字段;失败的任务会退款。

一次请求能拿到多张图片或 Base64 输出吗?

不能。Seedream 5.0 Pro 每次请求只返回一张图,n 大于 1 会返回 400。需要多个变体时,请发送多次请求,或使用支持组图的 Seedream 5.0 Lite。

结果始终是 URL,可用 output_format 选择 jpeg 或 png。Base64 只支持 image_urls 中的输入图片,不支持输出。

避免丢失生成图像的最佳办法是什么?

图片链接的有效期为 72 小时,结果里的 expires_at 会告诉你确切的过期时间。

任务一变为 completed 就把图片下载到自己的存储,并自行记录 task_id。不要把返回的 URL 当作永久存储。

标签#Seedream 5.0 Pro#图像生成#API 教程#开发者

关于 APIMart 团队

APIMart 团队为使用 AI 构建产品的开发者撰写模型解析、横向对比和价格拆解。APIMart 用一个 API 接入多家厂商的对话、图像和视频模型,你可以在上线前把文中提到的模型放在一起对比测试。

看完就试试

去模型市场挑选你想要的模型

在 APIMart 模型市场尝试聊天、图像和视频模型,用统一 API 快速体验模型能力。

聊天模型图像模型视频模型
进入模型市场