Reach APIReach API
进入 Dashboard
API ReferenceImage APIs

Seedream 接口

本平台对外提供模型 ID 为 seedream-4-5、seedream-5-0-lite 和 seedream-5-0-pro 的异步图片生成接口。

本文档面向客户端调用方，重点说明公开请求路径、认证方式、请求参数，以及任务结果的返回契约。

说明：

  • 提交任务：POST /v1/images/create
  • 查询任务：GET /v1/tasks/{task_id}
  • 模型 ID：seedream-4-5、seedream-5-0-lite、seedream-5-0-pro
  • 执行方式：异步任务
  • 典型场景：文生图、图像编辑、批量连续生成
  • 输入图片：仅支持通过 input.image_urls 传 URL

1. 接口概览

  • 请求方法：POST
  • 请求路径：/v1/images/create
  • Content-Type：application/json
  • 结果获取方式：
    • 提交接口只返回任务受理结果
    • 最终结果需要轮询 /v1/tasks/{task_id}，或通过 callback_url 接收

2. 认证与请求头

请求头示例：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json
请求头必填说明
Authorization是平台 API Key，格式：Bearer sk-xxxxxx
Content-Type是固定为 application/json

3. 提交任务

请求体示例：

{
  "model": "seedream-5-0-pro",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A premium product hero image, square composition, clean studio lighting",
    "image_urls": [],
    "resolution": "2k",
    "output_format": "png",
    "watermark": false,
    "sequential_image_generation": "disabled"
  }
}

3.1 顶层参数说明

字段类型必填说明
modelstring是固定传 seedream-4-5、seedream-5-0-lite 或 seedream-5-0-pro
callback_urlstring否任务终态回调地址，仅支持 https，最大长度 2048，本地、内网及私网目标会被拒绝
inputobject是图片生成参数

3.2 input 参数说明

字段类型必填说明
promptstring是生成提示词；比例、构图、用途等需求可写进提示词
image_urlsarray<string>否参考图 URL 列表。不传或传空数组表示文生图，非空表示图像编辑。seedream-5-0-pro 最多 10 张，其他型号最多 14 张
resolutionstring否输出分辨率档位。seedream-4-5 支持 2k、4k；seedream-5-0-lite 支持 2k、3k、4k；seedream-5-0-pro 支持 1k、2k，默认 2k
sizestring否输出尺寸，优先级高于 resolution；支持模型对应的分辨率档位或像素尺寸，如 2048x2048、3750x1250
output_formatstring否seedream-5-0-lite 和 seedream-5-0-pro 支持；可选值：png、jpeg。seedream-4-5 不支持该字段，默认输出 JPEG
watermarkboolean否是否添加上游水印；不传时按上游默认值处理
sequential_image_generationstring否是否启用批量连续生成；可选值：auto、disabled；不传时按上游默认 disabled 处理
sequential_image_generation_optionsobject否批量连续生成参数，仅在 sequential_image_generation 为 auto 时生效
optimize_prompt_optionsobject否提示词优化参数；seedream-5-0-pro 支持 standard 和 fast，其他型号仅支持 standard

sequential_image_generation_options 参数：

字段类型必填说明
max_imagesinteger否本次最多生成图片数；sequential_image_generation 为 auto 时取值范围为 1 到 15；参考图数量加 max_images 不能超过 15

optimize_prompt_options 参数：

字段类型必填说明
modestring否提示词优化模式；standard 为默认值、偏重质量；fast 可降低延迟但可能牺牲部分质量，且仅 seedream-5-0-pro 支持

说明：

  • Seedream 不支持 input.aspect_ratio。如需比例控制，请写进提示词，或直接传 input.size。
  • 平台始终采用异步任务链路。
  • 任务结果主契约为 data[].url。
  • 本地图片请先调用 POST /v1/images/uploads 上传，再将返回的 URL 填入 input.image_urls。
  • 即使 Pro 上游模型直接支持 Base64，Base64 图片输入也不属于 ReachAPI 的公开接口契约。

4. 请求示例

4.1 文生图请求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4-5",
    "input": {
      "prompt": "A quiet ceramic tea cup on a wooden table, square composition, soft morning light",
      "resolution": "2k",
      "watermark": false
    }
  }'

4.2 指定输出格式的文生图请求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "A premium skincare bottle hero image, 4:5 vertical poster composition, clean studio lighting",
      "resolution": "3k",
      "output_format": "png",
      "watermark": false
    }
  }'

4.3 图像编辑请求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4-5",
    "input": {
      "prompt": "Turn this sneaker photo into a clean e-commerce hero image, keep the original product shape",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "2k"
    }
  }'

4.4 自定义尺寸请求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "A wide cinematic concept art image for a sci-fi city skyline",
      "size": "3750x1250",
      "output_format": "jpeg"
    }
  }'

4.5 批量连续生成请求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "input": {
      "prompt": "Create a coherent set of 4 product lifestyle images for the same perfume bottle",
      "image_urls": [
        "https://cdn.example.com/reference-1.png"
      ],
      "resolution": "2k",
      "sequential_image_generation": "auto",
      "sequential_image_generation_options": {
        "max_images": 4
      }
    }
  }'

4.6 提示词优化请求

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "A restaurant poster for a summer tasting menu",
      "resolution": "2k",
      "optimize_prompt_options": {
        "mode": "fast"
      }
    }
  }'

4.7 Seedream 5.0 Pro 交互式编辑

seedream-5-0-pro 支持通过自然语言描述输入图上的手绘标记来指定局部编辑区域。如需更精确的位置控制，可在提示词中使用 <point> 或 <bbox> 坐标标签。

curl -X POST "https://direct.reachapi.ai/v1/images/create" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "input": {
      "prompt": "使用图 2 中 <bbox>118 331 933 871</bbox> 的主体，替换图 1 中 <bbox>179 283 796 986</bbox> 的主体。",
      "image_urls": [
        "https://cdn.example.com/base-image.png",
        "https://cdn.example.com/subject-reference.png"
      ],
      "resolution": "2k",
      "output_format": "png",
      "watermark": false
    }
  }'

坐标标签用于说明编辑区域和目标位置，不能替代 image_urls。仍需按提示词引用顺序传入对应图片。

5. 提交响应

响应示例：

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

字段说明：

字段类型说明
codeinteger平台业务状态码
msgstring错误或状态信息
statusstring初始任务状态，通常为 queued
task_idstring任务唯一 ID，后续用于查询
dataarray提交阶段为空数组

6. 查询任务

请求示例：

curl -X GET "https://direct.reachapi.ai/v1/tasks/task_xxx" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY"

状态说明：

状态说明
queued已受理，等待执行
generating生成中
success生成成功
failed生成失败

成功响应示例：

{
  "code": 200,
  "msg": "",
  "status": "success",
  "task_id": "task_xxx",
  "data": [
    {
      "url": "https://cdn.example.com/generated/image-1.jpeg"
    }
  ]
}

失败响应示例：

{
  "code": 500,
  "msg": "Model service request failed",
  "status": "failed",
  "task_id": "task_xxx",
  "data": []
}

说明：

  • 返回主契约是 data[].url。
  • 批量连续生成可能返回多张图片，按 data[] 数组承载。
  • 如果批量任务中部分图片被上游内容过滤或生成失败，平台只返回成功生成的图片；如果没有任何成功图片，任务失败。

7. 回调说明

如果提交任务时传了 callback_url，任务进入终态后，网关会向该地址发送 POST 请求。回调 body 与任务查询接口的响应结构一致。

回调约束：

  • 仅支持 https 地址
  • 最大长度 2048
  • localhost、.local 以及明显的私网目标会被拒绝
  • 单次投递超时 10s
  • 失败后最多重试 2 次，总计最多投递 3 次

8. 参数约束与不支持字段

  • prompt 不能为空
  • seedream-5-0-pro 的 image_urls 最多 10 张；seedream-4-5 和 seedream-5-0-lite 最多 14 张
  • image_urls 必须是服务端可访问的 https URL
  • seedream-5-0-pro 输入格式支持 jpeg、png、webp、bmp、tiff、gif、heic、heif
  • Pro 每张输入图：文件不超过 30MB；宽、高均须大于 14px；宽高比在 1/16 到 16 之间；总像素不超过 36,000,000（6000x6000）
  • seedream-4-5 的 resolution 可选 2k、4k
  • seedream-5-0-lite 的 resolution 可选 2k、3k、4k
  • seedream-5-0-pro 的 resolution 可选 1k、2k，默认 2k
  • size 可传模型支持的分辨率档位或 <width>x<height> 格式的像素尺寸
  • seedream-5-0-pro 使用自定义像素 size 时，总像素须在 921,600（1280x720）到 4,624,220（2048x2048x1.1025）之间，宽高比须在 1/16 到 16 之间
  • seedream-4-5 和 seedream-5-0-lite 使用自定义像素 size 时，总像素须在 2560x1440 到 4096x4096 之间，宽高比须在 1/16 到 16 之间
  • sequential_image_generation 只允许 auto、disabled
  • seedream-5-0-pro 的 optimize_prompt_options.mode 可选 standard、fast；其他型号仅允许 standard
  • seedream-5-0-pro 的交互式编辑支持在 prompt 中使用自由标记及 <point> / <bbox> 坐标标签
  • 上游生成图片 URL 仅保留 24 小时，请及时下载或持久化保存
  • watermark 必须是 boolean

公开接口不支持的输入字段包括：

  • input.image_base64s
  • 任意图片输入字段中的 Base64 图片数据
  • input.aspect_ratio
  • input.system_prompt
  • input.enable_web_search
  • input.stream
  • input.response_format
  • input.seed
  • input.guidance_scale
  • input.n
  • input.quality
  • input.background
  • input.moderation
  • input.negative_prompt

GPT Image 2.5 图片接口

Previous Page

nanobanana 接口

Next Page

On this page

1. 接口概览
2. 认证与请求头
3. 提交任务
3.1 顶层参数说明
3.2 input 参数说明
4. 请求示例
4.1 文生图请求
4.2 指定输出格式的文生图请求
4.3 图像编辑请求
4.4 自定义尺寸请求
4.5 批量连续生成请求
4.6 提示词优化请求
4.7 Seedream 5.0 Pro 交互式编辑
5. 提交响应
6. 查询任务
7. 回调说明
8. 参数约束与不支持字段