Seedream API

This platform provides an asynchronous image-generation endpoint for the public model IDs seedream-4-5, seedream-5-0-lite, and seedream-5-0-pro.

This document is for client integrations. It covers the public request path, authentication, request parameters, and task result contract.

Notes:

• Create task: POST /v1/images/create
• Query task: GET /v1/tasks/{task_id}
• Model IDs: seedream-4-5, seedream-5-0-lite, seedream-5-0-pro
• Execution mode: asynchronous task
• Typical use: text-to-image, image editing, sequential image generation
• Input images: URL input only through input.image_urls

1. Overview

• Request method: POST
• Request path: /v1/images/create
• Content-Type: application/json
• Result retrieval:
  • The create endpoint only returns task acceptance
  • Poll /v1/tasks/{task_id} or receive the final state through callback_url

2. Authentication

Request headers:

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

3. Create Task

Request body example:

{
  "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 Top-Level Parameters

3.2 input Parameters

sequential_image_generation_options:

optimize_prompt_options:

Notes:

• Seedream does not support input.aspect_ratio. Put ratio requirements in the prompt, or pass input.size.
• The platform always uses the asynchronous task flow.
• The task result contract is data[].url.
• Local files should first be uploaded with POST /v1/images/uploads, then passed through input.image_urls.
• Base64 image input is not part of the ReachAPI public contract for these models, even though the upstream Pro model supports it directly.

4. Request Examples

4.1 Text-to-Image

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 Text-to-Image with Output Format

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 Image Editing

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 Custom Size

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 Sequential Image Generation

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 Prompt Optimization

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 Interactive Editing

seedream-5-0-pro can target a local edit through natural-language descriptions of marks drawn on the input image. For more precise placement, include <point> or <bbox> coordinate tags in the prompt.

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": "Use the subject in Image 2 <bbox>118 331 933 871</bbox> to replace the subject in Image 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
    }
  }'

Coordinate tags identify edit regions and target positions; they do not replace image_urls. The referenced images must still be supplied in the same order used by the prompt.

5. Create Response

Response example:

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

6. Query Task

Request example:

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

Task states:

Success response example:

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

Failure response example:

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

Notes:

• The primary response contract is data[].url.
• Sequential generation may return multiple images in data[].
• If some images are filtered or fail during sequential generation, only successful images are returned. If no image succeeds, the task fails.

7. Callback

If callback_url is provided when creating the task, the gateway sends a POST request when the task reaches a terminal state. The callback body matches the task query response.

Callback constraints:

• Only https URLs are supported
• Maximum length is 2048
• localhost, .local, and obvious private network targets are rejected
• Single delivery timeout is 10s
• Failed delivery is retried up to 2 times, for at most 3 delivery attempts in total

8. Constraints and Unsupported Fields

• prompt is required and cannot be empty
• seedream-5-0-pro supports up to 10 image_urls; seedream-4-5 and seedream-5-0-lite support up to 14
• image_urls must contain server-accessible https URLs
• seedream-5-0-pro input formats: jpeg, png, webp, bmp, tiff, gif, heic, and heif
• For each Pro input image: file size must not exceed 30MB; width and height must each be greater than 14px; aspect ratio must be between 1/16 and 16; total pixels must not exceed 36,000,000 (6000x6000)
• seedream-4-5 resolution values: 2k, 4k
• seedream-5-0-lite resolution values: 2k, 3k, 4k
• seedream-5-0-pro resolution values: 1k, 2k; default is 2k
• size can be a supported resolution tier or a pixel size in <width>x<height> format
• For seedream-5-0-pro, custom pixel size must contain between 921,600 (1280x720) and 4,624,220 (2048x2048x1.1025) total pixels, with an aspect ratio between 1/16 and 16
• For seedream-4-5 and seedream-5-0-lite, custom pixel size total pixels must be between 2560x1440 and 4096x4096, with an aspect ratio between 1/16 and 16
• sequential_image_generation only allows auto and disabled
• seedream-5-0-pro allows optimize_prompt_options.mode values standard and fast; the other models allow only standard
• seedream-5-0-pro interactive editing supports freeform marks and <point> / <bbox> coordinate tags in prompt
• Upstream-generated image URLs are retained for 24 hours; download or persist results promptly
• watermark must be a boolean

Unsupported public input fields include:

• input.image_base64s
• Base64 image data in any image input field
• 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