Seedream 5 API Guide: Generate and Edit Images

The Seedream 5 API lets an application submit image generation work without exposing an API key in browser code. This guide covers the production workflow: create a task, store its ID, poll for status, and deliver the resulting image URLs when the task succeeds.

For the exact endpoint reference and current credit matrix, keep the Seedream 5 API documentation open while you integrate.

Integration flow

Seedream image generation is asynchronous. Treat a generation request as a job rather than a normal request that stays open until an image is ready.

1. Your server validates the user request.
2. Your server calls POST /api/generate with its API key.
3. The API returns a task_id.
4. Your server stores that ID and polls GET /api/status?task_id=....
5. A successful task returns one or more image URLs.
6. Your application stores or displays the result.

This pattern prevents long browser requests, gives the UI a real progress state, and makes retries easier to control.

Keep the API key on your server

Never place a Seedream API key in client-side JavaScript, a public environment variable, an SSR payload, or a mobile application bundle. A user who can inspect the bundle can extract the key and spend its credits.

Create a small backend endpoint in your own application. The browser calls your endpoint, and your server calls Seedream 5 with an authorization header:

POST https://seedream45ai.org/api/generate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Add authentication and per-user rate limits before forwarding a request. Log the returned task ID, but redact the authorization header from logs.

Submit a text-to-image task

A minimal high-quality request contains a prompt, an aspect ratio, and a quality setting:

{
  "prompt": "Editorial product photograph of a black ceramic watch on pale stone, soft window light, clean reflections, readable dial",
  "aspectRatio": "4:3",
  "quality": "high",
  "imageUrls": []
}

Write prompts as production briefs. Name the subject, environment, light, composition, and constraints. Avoid long lists of decorative adjectives that do not change the final decision.

The API responds with an opaque task identifier:

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "sd5_example_task_id"
  }
}

Store this ID with the user, request parameters, and creation time. Do not infer task state from elapsed time.

Poll status responsibly

Call the status endpoint with the returned ID:

GET https://seedream45ai.org/api/status?task_id=sd5_example_task_id
Authorization: Bearer YOUR_API_KEY

Your application should handle four states:

Status	Application behavior
PENDING	Show that the task is queued and poll again later.
IN_PROGRESS	Keep the progress state; do not create a duplicate task.
SUCCESS	Persist the response URLs and stop polling.
FAILED	Show a recoverable error and let the user revise or retry.

Use bounded exponential backoff rather than polling continuously. Stop after a reasonable application-level timeout, while keeping the task ID so the user can check it again.

Add reference images

For image-to-image work, pass accessible reference URLs in imageUrls. The prompt should explain what to preserve and what to change. For example:

{
  "prompt": "Keep the bottle shape, label layout, and camera angle. Replace the background with dark green stone and add soft side lighting.",
  "aspectRatio": "4:3",
  "quality": "high",
  "imageUrls": ["https://cdn.example.com/reference/product.jpg"]
}

Use stable HTTPS URLs that the generation service can retrieve. Do not use short-lived browser object URLs. The Seedream 5 image-to-image guide explains reference preparation and prompt structure in more detail.

Handle credits and failures

Check the current Seedream 5 pricing and credit rules before estimating unit economics. A production integration should record consumed_credits from the final task response rather than calculate spend from assumptions.

Handle these classes of failure separately:

• 401: the key is missing, invalid, or sent in the wrong place.
• 402: the account does not have enough credits for the request.
• 429: slow down creation or polling and retry with backoff.
• 500: preserve the task context and retry only when the operation is safe.

If a create request times out after reaching the server, check your task records before submitting the same work again. Blind retries can create duplicate jobs.

Production checklist

• Proxy all generation calls through your server.
• Apply user authentication, quotas, and prompt length limits.
• Store every task ID before polling.
• Use backoff and a maximum polling duration.
• Redact API keys and private reference URLs from logs.
• Persist successful images to storage you control when long-term availability matters.
• Surface credit and moderation errors with a clear recovery action.

Start with the interactive Seedream 5 AI Image Generator, then use the API documentation to connect the same workflow to your application.