如何使用 Seedream 5.0 Pro 图像 API

你只需一个 POST 请求、一个 API key 和一个后续步骤，就能让 Seedream 5.0 Pro 跑起来： 提交作业，拿到一个 task_id，然后不断查询状态直到图像完成。如果你漏掉第二步，就拿不到最终文件。

这里是简短版本：

• 我把请求发到 https://api.apimart.ai/v1/images/generations
• 我加上 Authorization: Bearer YOUR_API_KEY
• 我把 model 设为 doubao-seedream-5-0-pro
• 我包含 prompt、size 和 n
• 我用 文生图 来产生新的图像创意
• 当我想让输出更贴近一张或多张参考图时，我用 图生图
• 我会尽快存下图像 URL，因为它们在 24 小时后过期
• 对于像 3K 图这类耗时较长的输出，我用异步作业，它可能需要约 35 到 50 秒
• 我会关注成本，因为定价约为每张图 $0.0320

我最想记住的一点： 把 key 放在服务端，把 n 作为数字传递，并对较长的作业使用轮询或 webhook。

有几个细节比看起来更重要。例如，401 往往意味着 key 缺失或 Bearer 格式不对。403 往往意味着 key 有效，但账户不能使用该模型或余额不足。而如果我用 Base64 输出，我需要在浏览器中显示之前自己加上 data:image/...;base64, 前缀。

快速对比

简而言之： 本指南展示我会如何设置认证、构建请求体、在 T2I 和 I2I 之间选择、处理异步作业，并在不丢文件、不浪费开销的情况下保存结果。

2. 设置 API 访问与认证

2.1 创建你的 APIMart 账户并生成 API key

前往 APIMart 网站并注册一个新账户 ^[8]。然后在你的控制台打开 API Key 管理页面并生成一个 API key ^[1][5]。

立刻复制那个 key 并把它存在服务端。密钥管理器或环境变量是最安全的存放处。

绝不要把你的 API key 放进前端代码或公开仓库。如果有人拿到那个 key，他们就能使用你的账户。在 Node.js 中，用 process.env.API_KEY 存储它。在 shell 环境中，用 export API_KEY="your-key-here" ^[1][6]。

在构建完整的请求流程之前，先发送一个小的 POST 请求以确认访问正常 ^[1][2]。如果你得到 200 OK 响应，说明你的 key 和权限都配置正确了。

之后，你就可以继续处理请求字段，包括 model 和 prompt。

2.2 设置 Base URL 与 Bearer 认证头

一旦你选好了 T2I 或 I2I 模式并准备好 key，在任何图像请求生效之前，你都需要先设置好认证。每个请求都要带上这些请求头：

Bearer 前缀很重要。漏掉它，请求就会失败 ^[2][5]。另外，Bearer 后面要正好用一个空格。

HTTP 状态码能帮你快速发现认证问题 ^[1][10]。401 Unauthorized 错误通常意味着 key 缺失、无效，或没带上 Bearer 前缀 ^[1][10]。403 Forbidden 错误通常意味着 key 本身有效，但账户没有模型访问权限或余额不足 ^[1][10]。

一个不错的排查办法是先用 cURL 测试。如果 cURL 能跑通但你的应用不行，那 bug 多半出在你应用的请求代码里 ^[2][6]。

认证设置好后，下一步是构建图像请求体。

3. 构建一个 Seedream 5.0 Pro 图像请求

3.1 必需字段：Model、Prompt、Size 和图像数量

认证设置好后，下一步是构建 JSON 请求体。

一个有效的请求体需要四个字段：model、prompt、size 和 n。

对于 Seedream 5.0 Pro，把 model 设为 doubao-seedream-5-0-pro ^[1]。prompt 字段接受一段自然语言描述，最多支持 5,000 个字符 ^[2]。size 字段控制输出尺寸或宽高比。常见值包括 1024x1024、2K，以及像 1:1 或 16:9 这样的宽高比 ^[1][2]。n 字段设置要生成多少张图像，通常从 1 到 15 ^[1][6]。

有一个小细节可能会绊倒人：n 必须是整数，而不是字符串。如果你传 "1" 而不是 1，API 会返回校验错误 ^[1][5]。

3.2 可选字段：参考图、Web 搜索和异步作业

image_urls 是图生图模式的主要字段。用它以 URL 或 Base64 data URI 的形式发送最多 14 张参考图。每张图必须小于 10 MB，并使用 1:3 到 3:1 之间的宽高比 ^[1]。如果你用 Base64，请包含完整的 Data URI 前缀 data:image/jpeg;base64,，否则请求会失败 ^[1][5]。

web_search 能帮上事实性或实时性的 prompt，比如时事或品牌 logo ^[4][7]。对于大多数标准图像生成，你用不到它。

对于异步或批量作业，callback_url 接受一个公开的 HTTPS 端点，APIMart 会把任务完成载荷 POST 到那里 ^[2]。

3.3 cURL 和 JavaScript 的示例 API 调用

这是一个用于生成单张 1024×1024 图像的最小可用 cURL 请求：

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

下面是同样的请求在 Node.js 中用 fetch 的写法：

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

把这个请求保持在服务端。绝不要在客户端代码中暴露你的 API key。

一旦你提交了请求，下一步就是解析响应载荷。

4. 处理响应并运行常见的图像工作流

4.1 解析图像 URL、Base64 输出和错误对象

请求完成后，无论你发送的是一张还是多张图像，响应的结构都保持不变。

成功的响应会返回一个 JSON 对象，包含四个顶层字段：model、created（一个 Unix 时间戳）、data（一个图像对象数组）和 usage ^[6]。每张生成的图像都会出现在 data 内，根据你请求的格式，表现为 url 或 b64_json 字符串。如果 n 大于 1，data 里会为每个输出包含一个图像对象。

如果你用了 URL 格式，data 中的每一项会把图像链接存在 .url 里。你可以把那个值设为浏览器中图像的 src。有一点要注意：这些是临时签名链接，24 小时后过期 ^[6]。对于生产应用，请立刻下载文件并保存到永久存储，而不是存储 URL。

如果你用了 Base64 格式，data 中的每一项会把原始字符串存在 .b64_json 里。它_不_包含 data:image/...;base64, 前缀 ^[6]。要在浏览器中显示它，请自己加上那个前缀：

img.src = "data:image/png;base64", + data.b64_json;

要在 Python 中把它保存为文件，先解码：

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

如果请求失败，响应会包含一个 code 字段和一个 message 字段 ^[6]。400 通常意味着不支持的尺寸或无效参数。401 意味着请求未授权。每次都把这两个字段记录下来。大多数情况下，message 会直接指向问题所在。

用这些字段来决定你应该存储、解码还是显示输出。

---

4.2 你可以用 Seedream 5.0 Pro 生成的三种常见图像类型

这三种模式与前面讲过的模式一一对应：纯文本、单参考和多参考。

• 纯文本营销视觉。 对于需要更多细节的活动素材，使用 3K 分辨率（size: "3K"），并写一个结构化的 prompt，从主体和场景布局开始，然后加上光照、风格和色彩细节。3K 生成需要 35–50 秒，所以异步通常更合适。

• 单参考产品变体。 使用图生图模式，在 image_urls 中放一张参考图，并写一个聚焦的 prompt，只改动你想改的东西，比如背景、光照或表面纹理。这能让产品的形状和细节比从零生成更贴近源图像。对于 3K 变体，使用 callback_url，因为每个任务可能需要约 40 秒 ^[2]。

• 面向品牌和角色一致性的多参考一致性。 如果你需要某个角色或品牌元素在多张图像中保持一致，通过 image_urls 传入最多 14 张参考图 ^[2][3]。当从参考输入创建多个输出时，把 sequential_image_generation 设为 auto，这样你在保留多样性的同时不会丢失视觉一致性 ^[5][4]。这非常适合社交内容系列、产品目录和角色设定图。

当响应格式与工作流相匹配时，这些模式往往效果最好。

---

4.3 同步与异步请求 & URL 与 Base64 响应

用这个对比来在上线集成之前选定响应格式。

对于异步作业，在第一次轮询前先等约 20 秒，然后每 3 秒查一次 ^[2]。在生产中，callback_url 是更好的选择，因为它避免了轮询循环并减少了服务器开销 ^[2][9]。

默认使用 URL 响应。只在你需要图像数据出现在同一个响应里时才切换到 Base64。

5. 可靠的 Seedream 5.0 Pro 集成最终检查清单

在你第一次成功的测试调用之后、在你扩展到生产之前，过一遍这份检查清单。这是一个简单的办法，用来抓住那些常常让上线戛然而止的问题。

认证与 key 安全。 把你的 API key 放在环境变量或密钥管理器里。用 Authorization: Bearer <your_key> 从你的后端发送请求。

在发送之前校验你的请求参数。 检查 model 字符串，把 n 作为整数传递，把 image_urls 保持在允许的限制之内，并确保请求的 size 是受支持的。

对于比快速预览耗时更长的作业，相应地调整你的交付路径。 根据输出大小设置超时，并对长时间运行的作业使用 callback_url 而不是轮询。

图像就绪后，把交付当作一个存储问题，而不仅仅是一个响应问题。 如果你用 URL 输出，请立刻下载文件并把它移入永久存储。签名 URL 在 24 小时后过期 ^[6]。

在扩大规模之前，先在一小批上测试 prompt。 Seedream 5.0 的计费约为每张生成图像 $0.0320 ^[2]。记录 createTime、completeTime 和 costTime，这样你就能监控延迟和支出 ^[2]。

常见问题

拿到 task_id 之后，我怎么查询一个异步图像作业？

用返回的 task_id 来查询你异步图像作业的状态。

向 API 给你的状态端点发送一个 GET 请求。在许多 API 中，它看起来像这样：

• /v1/tasks/{task_id}
• 或者一个带 task_id 的查询式端点

在生产使用中，创建任务后先等约 20 秒，再做第一次状态检查。之后每 3 秒轮询一次，直到作业状态显示为 completed。

作业完成后，读取响应载荷并从中取出图像 URL。

我什么时候该用 URL 输出而不是 Base64？

大多数情况下用 URL 输出。它给你一个指向生成图像的直接链接，这让你更容易把它接入 Web 或移动应用。

只在你的配置需要图像数据内联在响应体中时才用 Base64，比如基于内存的处理，或当你想省掉第二次请求时。对于高分辨率的 4K 素材，URL 输出通常更高效。

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

及时保存生成的图像，因为 API 图像链接只在 72 小时内有效。

Seedream 5.0 Pro API 是异步运行的。这意味着你不会立刻拿到图像 URL。你先拿到一个 task ID，然后用那个 task ID 去获取图像 URL。

为避免丢失输出，你有两个主要选择：

• 用 task ID 轮询，直到图像就绪
• 使用一个回调 URL，让你的系统在链接过期前接收、捕获并存储图像

如果你等太久，URL 就会过期，图像可能就丢了。