How to Use Seedream 5.0 Pro to Generate Images

You can get Seedream 5.0 Pro working with one POST request, one API key, and one follow-up step: submit the job, get a task_id, then check status until the image is done. If you miss that second step, you won’t get the final file.

Here’s the short version:

• I send requests to https://api.apimart.ai/v1/images/generations
• I add Authorization: Bearer YOUR_API_KEY
• I set model to doubao-seedream-5-0-pro
• I include prompt, size, and n
• I use text-to-image for new image ideas
• I use image-to-image when I want the output to stay closer to one or more reference images
• I store image URLs fast, because they expire after 24 hours
• I use async jobs for slow outputs like 3K images, which can take about 35 to 50 seconds
• I watch cost, since pricing is about $0.0320 per image

The main thing I’d remember: keep the key on the server, pass n as a number, and use polling or a webhook for longer jobs.

A few details matter more than they seem. For example, 401 often means the key is missing or the Bearer format is wrong. 403 often means the key works, but the account can’t use the model or has low balance. And if I use Base64 output, I need to add the data:image/...;base64, prefix myself before showing it in a browser.

Key Takeaways

• Seedream 5.0 Pro is called with a POST request to https://api.apimart.ai/v1/images/generations using the header Authorization: Bearer YOUR_API_KEY and model set to doubao-seedream-5-0-pro.
• Every request needs model, prompt (up to 5,000 characters), size such as 1024x1024, 2K or 16:9, and n as an integer, usually from 1 to 15.
• Image-to-image mode sends up to 14 reference images through image_urls, each under 10 MB with an aspect ratio between 1:3 and 3:1, while 401 errors usually mean a missing key or Bearer prefix.
• 3K images take about 35 to 50 seconds, so use async jobs: wait about 20 seconds before the first poll and then poll every 3 seconds, or set callback_url.
• Generated image URLs expire after 24 hours, so download files to permanent storage right away, and test prompts on a small batch since pricing is about $0.0320 per image.

Quick comparison

In short: this guide shows how I’d set up auth, build the request body, choose between T2I and I2I, handle async jobs, and save the result without losing files or wasting spend.

2. Set Up API Access and Authentication

2.1 Create Your APIMart Account and Generate an API Key

Go to the APIMart website and sign up for a new account ^[8]. Then open the API Key Management Page in your dashboard and generate an API key ^[1][5].

Copy that key right away and store it on the server side. A secret manager or environment variable is the safest place for it.

Never put your API key in frontend code or a public repo. If someone gets that key, they can use your account. In Node.js, store it with process.env.API_KEY. In a shell environment, use export API_KEY="your-key-here" ^[1][6].

Before you build the full request flow, send a small POST request to make sure access works ^[1][2]. If you get a 200 OK response, your key and permissions are set up correctly.

After that, you can move on to the request fields, including the model and prompt.

2.2 Set the Base URL and Bearer Authentication Header

Once you've picked T2I or I2I mode and have your key ready, you need to set up authentication before any image request will work. Send these headers with every request:

The Bearer prefix matters. Leave it out, and the request will fail ^[2][5]. Also use exactly one space after Bearer.

HTTP status codes help you spot auth issues fast ^[1][10]. A 401 Unauthorized error usually means the key is missing, invalid, or the Bearer prefix wasn't included ^[1][10]. A 403 Forbidden error usually means the key itself is valid, but the account doesn't have model access or enough balance ^[1][10].

A good way to sanity-check this is to test with cURL first. If cURL works but your app doesn't, the bug is probably in your app's request code ^[2][6].

With auth set, the next step is building the image request body.

3. Build a Seedream 5.0 Pro Image Request

3.1 Required Fields: Model, Prompt, Size, and Image Count

With auth set up, the next step is building the JSON body.

A valid request body needs four fields: model, prompt, size, and n.

For Seedream 5.0 Pro, set model to doubao-seedream-5-0-pro ^[1]. The prompt field accepts a natural-language description and supports up to 5,000 characters ^[2]. The size field controls the output dimensions or aspect ratio. Common values include 1024x1024, 2K, and aspect ratios like 1:1 or 16:9 ^[1][2]. The n field sets how many images to generate, usually from 1 to 15 ^[1][6]. You can try Seedream 5.0 Pro on APIMart.

One small detail can trip people up: n must be an integer, not a string. If you pass "1" instead of 1, the API returns a validation error ^[1][5].

3.2 Optional Fields: Reference Images, Web Search, and Async Jobs

image_urls is the main field for image-to-image mode. Use it to send up to 14 reference images as URLs or Base64 data URIs. Each image must be under 10 MB and use an aspect ratio between 1:3 and 3:1 ^[1]. If you're using Base64, include the full Data URI prefix - data:image/jpeg;base64, - or the request will fail ^[1][5].

web_search can help with factual or real-time prompts, such as current events or brand logos ^[4][7]. For most standard image generations, you won't need it.

For async or batch jobs, callback_url accepts a public HTTPS endpoint where APIMart will POST the task completion payload ^[2].

3.3 Sample API Calls in cURL and JavaScript

Here’s a minimal working cURL request for a single 1024×1024 image:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

And here’s the same request in Node.js with fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Keep this request server-side. Never expose your API key in client-side code.

Once you submit the request, the next step is parsing the response payload.

4. Handle Responses and Run Common Image Workflows

4.1 Parse Image URLs, Base64 Output, and Error Objects

Once the request finishes, the response shape stays the same whether you sent one image or several.

A successful response returns a JSON object with four top-level fields: model, created (a Unix timestamp), data (an array of image objects), and usage ^[6]. Each generated image appears inside data as either a url or a b64_json string, based on the format you asked for. If n is greater than 1, data includes one image object per output.

If you used URL format, each item in data stores the image link in .url. You can set that value as an image src in the browser. One catch: these are temporary signed links, and they expire after 24 hours ^[6]. For production apps, download the file right away and save it to permanent storage instead of storing the URL.

If you used Base64 format, each item in data stores the raw string in .b64_json. It does not include the data:image/...;base64, prefix ^[6]. To show it in a browser, add that prefix yourself:

img.src = "data:image/png;base64", + data.b64_json;

To save it as a file in Python, decode it first:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

If the request fails, the response includes a code and a message field ^[6]. A 400 usually means an unsupported size or an invalid parameter. A 401 means the request is unauthorized. Log both fields every time. In most cases, the message points straight to the problem.

Use these fields to decide whether you should store, decode, or display the output.

---

4.2 Three Common Image Types You Can Generate with Seedream 5.0 Pro

These three patterns line up with the modes covered earlier: text-only, single-reference, and multi-reference.

• Text-only marketing visuals. For campaign assets that need more detail, use 3K resolution (size: "3K") and write a structured prompt that starts with the subject and scene layout, then adds lighting, style, and color details. 3K generation takes 35–50 seconds, so async is usually the better fit.

• Single-reference product variations. Use image-to-image mode with one reference image in image_urls and a focused prompt that changes only what you want, like the background, lighting, or surface texture. This keeps the product's shape and details closer to the source image than generating from scratch. For 3K variations, use callback_url, since each task can take around 40 seconds ^[2].

• Multi-reference consistency for brand and character consistency. If you need a character or branded element to stay consistent across several images, pass up to 14 reference images through image_urls ^[2][3]. Set sequential_image_generation to auto when creating multiple outputs from reference inputs so you keep variety without losing visual consistency ^[5][4]. This works well for social content series, product catalogs, and character sheets.

These patterns tend to work best when the response format matches the workflow.

---

4.3 Sync vs. Async Requests and URL vs. Base64 Responses

Use this comparison to pick the response format before you ship the integration.

For async jobs, wait about 20 seconds before the first poll, then check every 3 seconds ^[2]. In production, callback_url is the better option because it avoids polling loops and cuts server overhead ^[2][9].

Use URL responses by default. Switch to Base64 only when you need the image data in the same response.

5. Final Checklist for a Reliable Seedream 5.0 Pro Integration

After your first successful test call, run through this checklist before you scale to production. It’s a simple way to catch the issues that tend to stop launches cold.

Authentication and key security. Keep your API key in an environment variable or a secrets manager. Send requests from your backend with Authorization: Bearer <your_key>.

Validate your request parameters before you send them. Check the model string, pass n as an integer, keep image_urls within the allowed limit, and make sure the requested size is supported.

For jobs that take longer than a quick preview, adjust your delivery path accordingly. Set timeouts based on output size, and use callback_url for long-running jobs instead of polling.

Once the image is ready, treat delivery as a storage problem, not just a response problem. If you use URL output, download the file right away and move it into permanent storage. Signed URLs expire after 24 hours ^[6].

Test prompts on a small batch before scaling up. Seedream 5.0 is billed at about $0.0320 per generated image ^[2]. Log createTime, completeTime, and costTime so you can watch latency and spend ^[2].

FAQs

How do I check an async image job after I get a task_id?

Use the returned task_id to check the status of your async image job.

Send a GET request to the status endpoint the API gives you. In many APIs, that looks like:

• /v1/tasks/{task_id}
• or a query-style endpoint with the task_id

For production use, wait about 20 seconds after creating the task before your first status check. After that, poll every 3 seconds until the job status shows completed.

Once the job is done, read the response payload and pull the image URLs from it.

When should I use URL output instead of Base64?

Use URL output in most cases. It gives you a direct link to the generated image, which makes it easier to plug into web or mobile apps.

Use Base64 only when your setup needs the image data inline in the response body, like memory-based processing or when you want to skip a second request. For high-resolution 4K assets, URL output is usually more efficient.

What’s the best way to avoid losing generated images?

Save generated images promptly, because API image links are only valid for 72 hours.

The Seedream 5.0 Pro API runs asynchronously. That means you won’t get the image URL right away. First, you get a task ID. Then you use that task ID to fetch the image URL.

To avoid losing the output, you have two main options:

• Poll with the task ID until the image is ready
• Use a callback URL so your system can receive, capture, and store the image before the link expires

If you wait too long, the URL will expire and the image may be lost.