Seedream 5.0 Pro

Quick example

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "a scarlet macaw on a mossy branch, cinematic god rays, magazine cover titled WILD BEAUTY",
    "size": "2K",
    "aspect_ratio": "16:9"
  }'

import requests

resp = requests.post(
    "https://reapi.ai/api/v1/images/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "doubao-seedream-5-0-pro",
        "prompt": "a scarlet macaw on a mossy branch, cinematic god rays",
        "size": "2K",
        "aspect_ratio": "16:9",
    },
    timeout=30,
)
print(resp.json())

const r = await fetch("https://reapi.ai/api/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "a scarlet macaw on a mossy branch, cinematic god rays",
    size: "2K",
    aspect_ratio: "16:9",
  }),
});
console.log(await r.json());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model":        "doubao-seedream-5-0-pro",
        "prompt":       "a scarlet macaw on a mossy branch, cinematic god rays",
        "size":         "2K",
        "aspect_ratio": "16:9",
    })
    req, _ := http.NewRequest("POST",
        "https://reapi.ai/api/v1/images/generations", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

Submit response

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "doubao-seedream-5-0-pro",
  "status": "processing",
  "created_at": 1735000000
}

Poll GET /api/v1/tasks/{id} (see the Tasks reference) until status === "completed". The completed payload's output.image_urls holds the generated image URL, valid for 72 hours. Mirror to your own storage if you need it longer.

Authentication

Every call needs a Bearer token. Generate keys at reapi.ai/settings/apikeys.

Authorization: Bearer YOUR_API_KEY

Keys carry the active workspace's billing scope — there is no separate project header.

Endpoint

POST /api/v1/images/generations
GET  /api/v1/tasks/{id}

Submission is async. The POST returns immediately with a task_id; the task endpoint returns the same envelope until completion. Polling does not consume credits.

Request body

model — required

string. Must be doubao-seedream-5-0-pro exactly.

prompt — string, required

string. Up to 32,000 characters. Free-form text describing the image. Detailed prompts that name the subject, composition, lighting, and style consistently produce better results. Seedream 5.0 Pro renders in-image text well — put headline or logo copy directly in the prompt.

Optional (and usually omitted) when layer_decomposition is true: without a prompt the model finds the main elements itself. In that mode the prompt may also carry <bbox>x1 y1 x2 y2</bbox> markers to name exact regions, with coordinates normalised to the 0–1000 range.

size — string, optional

Output dimensions. Two forms, and they are mutually exclusive:

Resolution tier — 1K, 1.5K, or 2K. Combine with aspect_ratio to pick the frame. 1.5K generates at higher quality than 1K; see Pricing for which band each tier x ratio lands in.

Exact pixels — WIDTHxHEIGHT, e.g. 1920x1080. Use this for any frame the presets do not cover, such as 4:5 (1024x1280) or 5:4 (1280x1024). Two constraints apply together:

• total pixels between 921,600 and 4,624,220
• aspect ratio within [1/16, 16]

A size whose ratio is inside that window but whose pixel total is outside it is scaled proportionally onto the nearest bound rather than rejected, so your aspect ratio is preserved: 512x512 is delivered as 960x960, 4096x4096 as 2150x2150. A ratio outside the window is rejected.

When size gives exact pixels, aspect_ratio is ignored — the frame is already fully determined.

Defaults to 1K. Note that this differs from the upstream model's own 2K default: reAPI always sends an explicit value so that a bare {model, prompt} request keeps the price it has always had.

With layer_decomposition: true the exact-pixel form is rejected upstream; use auto, 1K, 1.5K, or 2K. Omitted size still defaults to 1K in that mode (the upstream model's own default there is auto); pass auto explicitly to have the output follow the input image's dimensions. In this mode auto and 1.5K are billed at the 2K rate, whatever quality says — the base image keeps the input image's aspect ratio, so its pixel count can land in the 2K band — see Layer decomposition pricing.

aspect_ratio — string, optional

Output aspect ratio, used when size is a resolution tier. Accepted values:

• 1:1
• 4:3
• 3:4
• 16:9
• 9:16
• 2:3
• 3:2
• 21:9

Defaults to 1:1. Ignored when size specifies exact pixels.

quality — string, optional

Resolution tier, kept for callers that integrated before size existed:

• basic — 1K output
• high — 2K output

Equivalent to size: "1K" / size: "2K". If both are present, size wins. New integrations should use size, which additionally reaches 1.5K and the exact-pixel form.

image_urls — array, optional

Reference images for image-to-image (1 image) or multi-reference fusion (up to 10 images). Public HTTP(S) URLs only — base64 / data: URIs are rejected at the gateway.

Upload to your own R2 / S3 / OSS / equivalent first, then pass the public URL.

output_format — string, optional

File type of the generated image: png or jpeg. Defaults to jpeg, or to png when background is "transparent".

With layer_decomposition: true this controls the base image only; every returned layer is always a PNG, because layers carry an alpha channel. background: "transparent" requires png and rejects jpeg.

optimize_prompt_options — object, optional

Prompt-optimization settings. One key:

• mode — standard (default) or fast. fast reduces generation latency at a slight cost in output quality.

{ "optimize_prompt_options": { "mode": "fast" } }

watermark — boolean, optional

Adds an "AI-generated" watermark to the lower-right corner. Defaults to false; the upstream model's own default is true, and reAPI always sends an explicit value so generated images are clean unless you ask otherwise.

layer_decomposition — boolean, optional

Defaults to false. When true, the model splits your reference image into a base image plus up to 16 independently editable layers. Each layer is a PNG with a real alpha channel, and the response carries per-layer metadata in output.layers — see Response.

Requires exactly one image in image_urls; zero or multiple are rejected. Cannot be combined with background: "transparent" — layers are already returned as transparent PNGs. Partial success is not supported: if any layer fails, the whole request fails. If your prompt asks for more layers than the model can produce, some layer content may be dropped rather than the request failing.

Billing is per image actually returned — see Pricing.

background — string, optional

Controls the alpha channel of the output. Defaults to opaque.

• opaque — a normal solid-background image
• transparent — a PNG with a real alpha channel

transparent requires exactly one image in image_urls and the source image must itself carry an alpha channel; text-to-image requests are rejected upstream. It also cannot be combined with layer_decomposition, and it rejects output_format: "jpeg". opaque carries no such restriction.

content_filter — boolean, optional

Controls the final-image content check and defaults to true. Direct API requests may pass false to skip this additional check. The hosted Playground always keeps it enabled.

When enabled, a flagged image is hidden and the task returns a content-policy error. Because the upstream generation already completed, that generation is still charged. Avoid submitting restricted-content prompts when using the Playground.

Pricing

Seedream 5.0 Pro charges the official per-output-image rate, banded by the pixel count of the image actually produced. One threshold splits the two bands, and it applies the same way whether you asked with a tier or with exact pixels:

All eight 1K ratios land in the lower band and all eight 2K ratios in the higher one. 1.5K straddles it: 1:1, 16:9, 9:16, 3:2 and 2:3 are in the lower band, while 4:3, 3:4 and 21:9 cross the threshold and are billed in the higher one. An exact WIDTHxHEIGHT is banded by its own pixel total — including a size that was scaled onto the window bounds, which is billed for the pixels actually delivered.

For reference-image requests, the first input image is included and each additional input image (2nd through 10th) adds the official ¥0.02 reference surcharge (converted at the configured 6.8 RMB/USD rate). Provider failures and requests rejected before an image is generated are refunded. An image blocked by the final output check is still charged because generation already completed.

credits = ceil((output_price_usd + additional_reference_price_usd) × 1000)

where 1 credit = $0.001. The exact per-image credit cost surfaces on the model page and reflects the current rate. There is no per-token or subscription component.

Layer decomposition

Because the model decides how many layers to produce, a layer_decomposition: true request is charged for the images you actually receive:

credits = (1 + layers_returned) × per_image_credits_at_your_quality_tier

Every returned image — the base image and each layer — is charged at the quality tier you requested. basic bills each of them at the 1K rate, high at the 2K rate. With size: "auto" or size: "1.5K" every image is billed at the 2K rate, since the base image follows the input image's dimensions or aspect ratio and can land in the 2K band. Reference-image surcharges apply to the base image only; layers are outputs, not additional inputs.

At submission time we reserve the worst case — the base image plus the maximum 16 layers — and refund the difference the moment the task settles, so you are never charged for layers the model did not return. A failed request is refunded in full.

Response

The poll envelope returns the image URL in output.image_urls:

{
  "id": "task_019dfd44b7fd74168541552a3260a623",
  "model": "doubao-seedream-5-0-pro",
  "status": "completed",
  "output": {
    "image_urls": [
      "https://cdn.reapi.ai/...jpg"
    ]
  }
}

URLs are valid for 72 hours. Mirror to your own storage for longer retention.

Layer decomposition output

A layer_decomposition: true task returns several images, and output.layers describes them positionally: layers[i] belongs to image_urls[i].

{
  "status": "completed",
  "output": {
    "image_urls": [
      "https://cdn.reapi.ai/...base.jpg",
      "https://cdn.reapi.ai/...layer1.png"
    ],
    "layers": [
      { "z_index": 0, "size": "2048x2048", "output_format": "jpeg" },
      {
        "z_index": 1,
        "size": "1273x265",
        "output_format": "png",
        "name": "Seedream title text",
        "description": "Large yellow serif title text",
        "bounding_box": {
          "absolute": [383, 120, 1655, 384],
          "normalized": [187, 59, 808, 188]
        }
      }
    ]
  }
}

• z_index — stacking order. 0 is the base image; layers start at 1 and a higher value sits on top.
• bounding_box — where the layer belongs, in the output base image's coordinate system. absolute is [left, top, right, bottom] in pixels; normalized is the same four edges scaled to the integer range [0, 1000]. The base image spans the whole canvas and carries no box.
• name / description — what the model identified in that layer.

To rebuild the original: place each layer at (left, top), scale it to (right - left) x (bottom - top), and composite in ascending z_index. Use normalized instead if you are compositing onto a canvas of your own size.

Errors

Failures use the standard envelope { error: { code, message, request_id } }. See the errors catalog for the full code list. Common cases:

• Invalid parameters (bad size / aspect_ratio, a ratio outside [1/16, 16], oversize image_urls) → 4xx invalid-input.
• A prompt or reference rejected before generation → content-policy error; the task is refunded.
• A generated image blocked by the enabled output check → content-policy error (80006); the image is hidden and the completed generation remains charged.

Tips

• Choose aspect_ratio explicitly instead of relying on ratio wording in the prompt.
• Multi-reference fusion keeps a character consistent — pass the same face / wardrobe references across a series.
• Lean on Seedream 5.0 Pro's text rendering for posters, covers, and UI mockups; spell the exact words you want in quotes inside the prompt.

Related

• Seedream 5.0 Lite — the lean, lower-cost tier
• Tasks reference
• Errors catalog