如何使用 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]。

常见问题

::: faq

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

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

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

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

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

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

::: faq

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

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

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

::: faq

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

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

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

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

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

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