Este artículo aún no está disponible en tu idioma; mostramos el original.
Blog

Guide

Seedream 5.5 Developer Guide: Capabilities, API Parameters, and Pricing

How to integrate text-to-image and image-to-image, pick sizes that cut cost, and avoid billing surprises

Nov 16, 2026 10 min read
Flat stepped horizontal color bands decreasing across a sand ground, overprinted with terracotta and brown blocks, cover art for the Seedream 5.5 guide.
En esta página

What Seedream 5.5 Actually Does

Seedream 5.5 is an image generation model exposed on HiAPI.ai under the route seedream-5.5. It has exactly two official capabilities: text-to-image and image-to-image. Everything you build with the route falls into one of these two shapes, and the same parameter set drives both.

In text-to-image mode, you send a prompt and receive a generated image. In image-to-image mode, you additionally pass one or more public reference images through image_urls, and the model uses them to guide composition, subject, or style. The prompt is still the steering mechanism: it describes what you want to generate, or — when references are present — what should be modified and what should be preserved.

Two practical implications follow from this scope. First, the model is image-out only; there is no text response to parse, no streaming tokens, and no tool-calling surface. Your integration is a single request that returns image data. Second, because both capabilities share one route, switching between pure generation and reference-guided generation is a matter of adding or omitting image_urls — not switching endpoints or model slugs.

If your use case is anything outside these two capabilities, this route is not the right fit, and no amount of parameter tuning will change that. Knowing the boundary up front saves you from over-engineering prompt workarounds.

Two official capabilities, shown as parallel flows: text alone to an image tile, and a reference image plus text to a new image tile.

The seedream-5.5 Route and Required Inputs

The route is identified by the slug seedream-5.5. A minimal request needs exactly one field:

The required field

  • prompt — string, required, minimum length 1, maximum length 5000. This is the description of the image you want to generate, or the instruction for how to modify and preserve content from reference images.

That is the entire mandatory surface. A request containing only a valid prompt will succeed, and — importantly — will be billed at the default size of 2K because size was omitted. Keep that default in mind; it is the single most common source of surprise on the first invoice.

The optional fields

  • aspect_ratio — string enum: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9, 2:1, 1:2. When omitted, the model selects the frame from the prompt and any reference images.
  • size — string enum: 1K, 1.5K, 2K. Defaults to 2K.
  • background — string enum: auto, transparent, opaque. Defaults to auto.
  • output_format — string enum: png, jpeg. Defaults to png.
  • image_urls — array of 1 to 10 public http(s) reference image URLs. Omit it entirely for pure text-to-image.

Minimal request shape

{
  "prompt": "A weathered lighthouse on a basalt cliff at dusk, cold blue light"
}

That single field is a valid call. Add size explicitly in production even when you want 2K — being explicit is documentation for the next engineer reading your code, and it makes cost review trivial.

The seedream-5.5 request path: a single required prompt input flows into the image output, while optional parameters branch off as secondary.

Choosing Size and Aspect Ratio

size controls the output pixel tier and is one of the few parameters with a direct price consequence. The official enum has three values: 1K, 1.5K, and 2K.

The tiers and the default

  • 1K and 1.5K share the same price tier.
  • 2K sits in a higher price tier.
  • Omitting size bills as 2K, because 2K is the default.

This default is deliberate on the platform side — highest quality unless told otherwise — but it means a prototype that never sets size is quietly running at the most expensive tier. If your product renders thumbnails, thumbnails plus a 1.5K preview path will cost materially less per image than the same calls left at default.

Aspect ratio behavior

aspect_ratio is a string enum with ten values: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9, 2:1, 1:2. When you omit it, the model chooses the frame based on the prompt and any reference images.

Automatic framing is genuinely convenient for freeform creative tools: the prompt "a wide cinematic desert vista" tends to produce a wide canvas without you specifying anything. But it is less predictable for fixed-layout pipelines — card grids, social templates, print slots. If your downstream renderer assumes a specific aspect ratio, always set aspect_ratio explicitly. Treat omission as a creative-mode feature, not a safe default.

One more constraint worth internalizing: the enum is the full list. There is no resolution tier outside 1K/1.5K/2K, so don't design around values that aren't in the official set.

Reference Images and Image-to-Image Billing

image_urls is how you turn a text-to-image call into image-to-image. It accepts an array of 1 to 10 public http(s) reference image URLs. Omit the field entirely and you get pure text-to-image.

What the model does with references

Each reference image is guidance. The prompt tells the model what to change and what to keep — that is why the prompt spec explicitly covers "describe what to change and what to keep, combined with the reference images" (combined with reference images, describe what to modify and what to preserve). A prompt that ignores the references wastes them; a prompt that names the parts to preserve gets far more predictable output.

The billing rule to internalize

Each reference image is billed separately. This is the single most important sentence in this section. A request with three reference images is not one billed unit — it is the base image plus per-reference charges accumulated on the same request. Sending the maximum of 10 references adds 10 × $0.0075 = $0.075 on top of the size-tier price.

Practical guidance

  • Send the minimum number of references that actually improves the result. Two well-chosen references usually beat eight marginal ones, at a fraction of the cost.
  • Do not loop over a user's photo library and pass everything. Curate first, then call.
  • Validate URLs before sending: they must be public http(s). Private, signed, or localhost URLs will fail at fetch time, and you'll have paid for the attempt's round trip rather than the image.
  • Keep reference resolution sane. You are billed per image, not per pixel, but oversized references still slow the request without improving fidelity.

Build a cost model that treats reference count as an additive surcharge, not a multiplier of the size-tier price. Official size-tier prices are $0.0186 at 1K and 1.5K, and $0.0325 at 2K (the default). Each reference image adds $0.0075. Total = tier price + (count × $0.0075). A 2K image with three references is $0.0325 + 3 × $0.0075 = $0.0550, not $0.0325 × 3. That one habit prevents most image-to-image invoice surprises.

Each reference image in a request adds its own billed unit, accumulating as a descending staircase of cost.

Output Format and Background Control

output_format is a two-value enum: png or jpeg, defaulting to png. background is a three-value enum: auto, transparent, or opaque, also defaulting to auto.

The one hard rule

Transparent background requires PNG output. If you set background to transparent but leave output_format at jpeg — or set it to jpeg explicitly — you will not get transparency. JPEG has no alpha channel. This is the most common format mistake on this route, and it's easy to avoid: whenever transparency matters, set output_format to png explicitly in the same request as background: transparent. Don't rely on the default to save you; a later refactor that adds output_format: jpeg for file-size reasons will silently break transparency.

Choosing between them

  • Use background: transparent with output_format: png for asset pipelines: product cutouts, UI stickers, layered composites, anything headed into an editor.
  • Use output_format: jpeg for photographic output where file size and bandwidth matter and the background will be flattened anyway — hero images, social previews, email headers.
  • Leave both at defaults when you genuinely don't care; the model will pick a sensible background and hand you PNG.

background: auto is a reasonable creative default, but it means the background decision is delegated to the model — sometimes transparent, sometimes opaque — so a pipeline that needs consistency should set both fields explicitly. Determinism is cheap here; just set the two parameters.

Pricing Breakdown and Cost Planning

Billing on seedream-5.5 is per image, based on the size tier. Current pricing is always shown on the model page itself, so treat that panel as the source of truth and use this section for the billing logic rather than a price list.

The billing model

  • Each generated image is one billed unit.
  • The unit price depends on size: 1K and 1.5K share one tier, 2K is a higher tier.
  • When size is omitted, the request bills at the 2K tier because 2K is the default.
  • Each entry in image_urls is billed separately, on top of the base image charge for that request.

Estimating before you build

The structure of the estimate matters more than any single number:

  1. Decide the size mix. If 80% of your traffic is thumbnails and you route those to the cheaper tier, your blended per-image cost drops well below the default-tier number you'd otherwise assume.
  2. Decide the reference policy. A three-reference request costs substantially more than a zero-reference request. Model the maximum reference count your UI allows as your worst-case per-request multiplier.
  3. Multiply by expected volume, not by calls. One call with four references is not one image's worth of spend.

The default-billing trap

Teams wire up the route, run a few hundred test calls with only prompt set, and are surprised that the test batch billed at the highest tier. The fix is procedural: set size explicitly everywhere from day one, including tests. Then the cost of a test run is a decision you made rather than a default you inherited.

Integration Checklist and Common Pitfalls

Before you ship, walk through this list. Each item maps to a failure mode described earlier in this guide.

Pre-launch checklist

  • prompt is present and non-empty. It is the only required field, with a minimum length of 1 and a maximum of 5000 characters. Guard against empty strings from caller forms.
  • size is set explicitly. Never let production rely on the default. Confirm 1K/1.5K for cheap paths and 2K only where quality demands it.
  • aspect_ratio is set for any fixed-layout renderer. Omitted values hand framing to the model, which is fine for creative tools and wrong for grids.
  • Transparency pairs correctly. background: transparent must be shipped with output_format: png. Assert this pairing in a unit test so a refactor can't break it.
  • Reference counts are deliberate. image_urls accepts 1 to 10 public http(s) URLs, each billed separately. Enforce a maximum in your own UI and validate URL reachability before the call.
  • Cost estimate uses the real multiplier. Volume times (tier price + average reference count × $0.0075). If that product surprises you, the reference policy is usually the culprit.

The three pitfalls that bite most often

  1. Silent default sizing. Most first-invoice surprises trace back to a request that never set size.
  2. Reference sprawl. Passing every candidate image instead of a curated few, inflating per-request cost.
  3. JPEG transparency. Requesting a transparent background with JPEG output and getting an opaque image instead.

When you're ready to wire it up, the route parameters and live pricing are documented on the Seedream 5.5 model page — set your defaults deliberately, and the route behaves predictably.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API