NewMiniMax H3 Lite is live: our cheapest video model, at a launch price until Dec 31. Try it free

OG filename: how-to-use-seedream-api-cover-v3.png
All guides
How-to

How to Use the Seedream API in 2026

Generate Seedream 5 Lite images at 2K and 3K from your own code with the AiWings API: create a key, send one request, and get a permanent image link. Step by step, in cURL, JavaScript and Python.

·5 min read·

How to Use the Seedream API in 2026

Want Seedream images in your own app, script or automation? This guide shows how to make them with the AiWings API, step by step. You use one AiWings key, pay per image from your AiWings credits, and get back a permanent link to every file. It takes about five minutes from no account to a finished image, and the same key also covers GPT Image, Nano Banana, Flux and video models.

What you need

  • An AiWings account. Sign in with Google; new accounts get 10 free credits, enough for 2 Seedream images.
  • An AiWings API key, which you create in the next step.
  • Somewhere to run code on a server: a script, a backend route, a serverless function or an automation tool that can send HTTP requests. Keys don’t work from browser or mobile app code, where anyone could read them.

Step 1: Create an API key

  1. 1Sign in to AiWings and open the API page in your dashboard.
  2. 2Click Create key, give it a name (for example “my-app production”) and, if you like, a monthly credit limit.
  3. 3Copy the key. It starts with aiw_live_ and is shown only once.
  4. 4Save it as an environment variable on the machine or service that will call the API.
export AIWINGS_API_KEY="aiw_live_your_key_here"

The API uses the same credits as AiWings in ChatGPT, Claude and the dashboard, so there’s no separate plan to buy. Every request sends the key in the Authorization header as a Bearer token.

Create an API key

Step 2: Know your options

AiWings offers Seedream 5 Lite, ByteDance’s image model. Set the size with quality and the shape with aspect_ratio:

Modelmodel valuequalityReference imagesCost per image
Seedream 5 Liteseedream-5-lite2K, 3KUp to 145 credits ($0.05)

Prices are at the top-up rate of $0.01 per credit, and plans include more credits per dollar. Each finished job reports exactly what it cost in its credits field, and GET /v1/models lists every price. Aspect ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9.

Step 3: Make your first image

Send a POST request to /v1/images with a prompt and the model. With "wait": true you get the finished image back in the same call. This one is a 21:9 panorama at 3K, which costs 5 credits ($0.05):

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "An ultra-wide photo of a vast white salt flat at dawn, a thin mirror of sky on the ground and distant mountains on the horizon",
6 "model": "seedream-5-lite",
7 "quality": "3K",
8 "aspect_ratio": "21:9",
9 "wait": true
10 }'
11
12# Still "processing"? Ask again with the id:
13curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
14 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

With "wait": true the request holds until the image is ready, for up to 60 seconds, so most images come back in one call with status "succeeded". Higher quality settings can take longer; if the status is still "processing", the loop asks again with GET /v1/images/{id}?wait=30.

output.url is a permanent link to the file. If an image fails, status is "failed", error.message says why, and the credits are refunded automatically. Every image you make through the API also shows up in your AiWings library.

Step 4: Keep your product, change the scene

Seedream is good at keeping a product exactly as it is while changing everything around it. Pass public image URLs in reference_images (up to 14) and describe the new scene. Already made the image with AiWings? Pass its id as source_generation_id instead.

1curl https://aiwings.io/api/v1/images \
2 -H "Authorization: Bearer $AIWINGS_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "prompt": "Put this coffee bag on a sunny kitchen counter next to a pour-over kettle, soft morning light, keep the label exactly as it is",
6 "model": "seedream-5-lite",
7 "quality": "2K",
8 "aspect_ratio": "3:4",
9 "reference_images": [
10 "https://example.com/coffee-bag.png"
11 ],
12 "wait": true
13 }'
14
15# Still "processing"? Ask again with the id:
16curl "https://aiwings.io/api/v1/images/IMAGE_ID?wait=30" \
17 -H "Authorization: Bearer $AIWINGS_API_KEY"
POST /v1/imagesShell

To upload a file from your computer first, use POST /v1/uploads, then pass the url it returns in reference_images. The API docs show the full flow.

See what Seedream makes

Real, unedited Seedream 5 Lite images, each made from a single request.

A mirror-like salt flat at blue hour reflecting the Milky Way, with distant rock monoliths on the horizon
Ultra-wide scenes at 21:9Seedream 5 Lite · 3K
The same kraft coffee bag from the reference image placed on a sunlit oak kitchen counter next to a pour-over setup
Keep your product, change the sceneSeedream 5 Lite · 2K
A fictional design magazine called ATLAS lying flat on pale concrete, with a white spiral staircase on the cover and three cover lines
Editorial layouts with textSeedream 5 Lite · 2K
A layered paper-cut diorama of a mountain village at dusk lit from behind, inside a shadow box
Illustration with real textureSeedream 5 Lite · 2K

More models with the same key

Your key isn’t limited to Seedream. The same key, balance and request format cover every video and image model on AiWings. To switch, change the model field: video models go to POST /v1/videos and image models to POST /v1/images.

Modelmodel valueEndpointFrom
Seedance 2.0seedance-2.0/v1/videos50 credits ($0.50) for 5 seconds at 480p
Seedance 2.5seedance-2.5/v1/videos65 credits ($0.65) for 5 seconds at 480p
MiniMax H3minimax-h3/v1/videos50 credits ($0.50) for 5 seconds at 768p
MiniMax H3 Highspeedminimax-h3-highspeed/v1/videos20 credits ($0.20) for 5 seconds at 768p
MiniMax H3 Liteminimax-h3-lite/v1/videos10 credits ($0.10) for 5 seconds at 480p
GPT Image 2.6 Flaregpt-image-2.6-flare/v1/images7 credits ($0.07) per image
GPT Image 2.6 Sunburstgpt-image-2.6-sunburst/v1/images7 credits ($0.07) per image
GPT Image 2.5 Flaregpt-image-2.5-flare/v1/images2 credits ($0.02) per image
GPT Image 2.5 Sunburstgpt-image-2.5-sunburst/v1/images2 credits ($0.02) per image
GPT Image 2gpt-image-2/v1/images2 credits ($0.02) per image
GPT Image 1.5gpt-image-1.5/v1/images2 credits ($0.02) per image
Nano Banananano-banana/v1/images5 credits ($0.05) per image
Nano Banana 2nano-banana-2/v1/images8 credits ($0.08) per image
Nano Banana Pronano-banana-pro/v1/images19 credits ($0.19) per image
Seedream 5 Liteseedream-5-lite/v1/images5 credits ($0.05) per image
Grok Imaginegrok-imagine/v1/images3 credits ($0.03) per image
Flux Fastflux-fast/v1/images1 credit ($0.01) per image

GET /v1/models returns the same list with every price, size and option, so your code can check what’s available instead of hard-coding it.

See every model with samples

Things to know

  • 2K and 3K cost the same, 5 credits ($0.05) per image, so use 3K whenever you need the extra detail.
  • Seedream handles text in images well, such as a magazine masthead or a label, so put the exact words in quotes in your prompt.
  • It accepts up to 14 reference images in one request, useful for a product plus a style or a scene to match.
  • Send an Idempotency-Key header with each new job (the JavaScript and Python examples do). If a request times out and you retry with the same key, you get the same job back instead of paying twice.
  • Each key has its own rate limit, and you can give each key a monthly credit cap so a bug in one app can’t spend your whole balance.
  • Output URLs are public but unguessable, like a share link. Download the file to your own storage if you need to control who can see it.

If something goes wrong

  • 401 authentication_failed: the key is missing, mistyped or revoked. Check the Authorization header reads Bearer followed by your key.
  • 400 invalid_request: a field isn’t allowed for that model, for example a quality or aspect ratio it doesn’t support. The error’s param names the field to fix.
  • 402 insufficient_credits: your balance can’t cover the image. Top up in the dashboard and send the request again.
  • 403 spend_limit_reached: this key hit its monthly credit limit. Raise or remove the limit on the API page.
  • 429 rate_limited or too_many_jobs: you’re sending too fast or have too many jobs rendering at once. Wait for the Retry-After time, or for a image to finish.
  • The image failed with a content error: the prompt or image was blocked by the model’s safety filter. Reword it; the credits were already refunded.

Bottom line

You don’t need a ByteDance account to put Seedream in your product. One AiWings key gives your code Seedream 5 Lite at 2K and 3K, plus GPT Image, Nano Banana, Flux and video models, billed from one balance, with permanent links and automatic refunds on failures. Prefer no code? The same models work in ChatGPT and Claude.

Read the full API reference

FAQ

Is this the official Seedream API?

No. AiWings is an independent service that runs Seedream for you. You use an AiWings key and AiWings credits, with no ByteDance account or separate billing.

How much does a Seedream image cost through the API?

5 credits ($0.05) per image at either 2K or 3K. Failed images are refunded.

Can I edit an existing image with Seedream?

Yes. Pass it in reference_images, or pass the id of an AiWings image as source_generation_id, and describe the change. Up to 14 reference images per request.

Can I use it from n8n, Make or Zapier?

Yes, any tool that can send an HTTP request works. Send the POST request from Step 3; with "wait": true the response already contains the image URL.