# A Practical Seedream Image API Workflow: Generate, Edit, and Poll Image generation APIs are easy to demo and surprisingly easy to integrate badly; this guide builds a small, production-minded workflow for generating, editing, and retrieving Seedream images without tying up your server. ![Seedream API workflow cover](https://cdn.acedata2.cloud/gpt-image/9138467b09fb1c406d9172d108ca7e4ff1af95df3e208df972cb7f7ea70f548a.png) ## What we are building We will use one HTTP endpoint for two related jobs: - generate an image from a text prompt; - edit one or more existing images with natural-language instructions. The base URL is `https://api.acedata.cloud`, and both operations use `POST /seedream/images`. Requests are JSON and authenticate with `Authorization: Bearer ${token}`. Ace Data Cloud is useful here as a thin API layer: the integration stays ordinary HTTP, so the same request pattern works from a script, backend route, queue worker, or automation tool. The important design choice is execution mode. A synchronous request is convenient for a local experiment, but image jobs may take roughly one to two minutes. For an application, set `async` to `true`, store the returned `task_id`, and poll `/seedream/tasks`. If you already run a public webhook, you can instead send a `callback_url` and associate the callback with the same task ID. ## Step 1: Generate a first image Start with the Lite model and a precise, testable prompt. The model name must be the full string; an abbreviated name can return HTTP 400. ```bash curl -X POST 'https://api.acedata.cloud/seedream/images' \ -H 'accept: application/json' \ -H 'authorization: Bearer ${token}' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "doubao-seedream-5-0-lite-260128", "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting", "size": "2K", "response_format": "url", "output_format": "png", "watermark": false }' ``` For Seedream 5.0 Lite, `size` accepts the `2K`, `3K`, and `4K` presets. You can also provide explicit width and height values when you need fixed dimensions. Keep these two sizing approaches separate rather than mixing a preset with pixel dimensions. A completed response includes `success`, `task_id`, `trace_id`, and a `data` list. Each result in `data` can include `prompt`, `size`, and `image_url`. In a real service, retain the `trace_id` with your logs: it gives you a useful reference when a request succeeds at the HTTP layer but produces an unexpected result. ## Step 2: Turn generation into editing Editing uses the same endpoint. The main difference is the `image` field, which supplies one or more source images. That makes it straightforward to build a two-stage flow: generate a stable base composition, then make targeted revisions without rewriting the entire prompt. ```python import requests response = requests.post( "https://api.acedata.cloud/seedream/images", headers={ "accept": "application/json", "authorization": "Bearer YOUR_TOKEN", "content-type": "application/json", }, json={ "model": "doubao-seedream-4-0-250828", "prompt": "Keep the composition unchanged. Replace the matte material with clear glass and preserve the neutral studio lighting.", "image": ["https://example.com/input.png"], "size": "2K", "watermark": False, }, timeout=180, ) response.raise_for_status() result = response.json() print(result["data"][0]["image_url"]) ``` The practical lesson is to separate invariants from edits. State what must remain unchanged—composition, pose, camera angle, or lighting—before describing the transformation. This makes iterative workflows easier to reason about and gives you a clean prompt history for debugging. Seedream 5.0 Pro can also accept up to ten input images, but it is a single-image output model. It does not support image groups, streaming, or web search. Choose the model for the workflow you need rather than assuming every parameter is portable across versions. ## Step 3: Move long jobs off the request path For a web application, avoid making the browser wait on image generation. Submit an asynchronous job instead: ```json { "action": "generate", "model": "doubao-seedream-5-0-lite-260128", "prompt": "A compact reading lamp on a walnut desk, soft evening light", "size": "2K", "async": true } ``` The API immediately returns a `task_id`. Persist it beside your own job record, then poll `/seedream/tasks` until the final result is available. This pattern gives you room to add retries, a progress state, and cancellation in your own UI without holding an application server connection open. If you use `callback_url`, validate the incoming payload, match it by `task_id`, and make the handler idempotent. Callback delivery and database writes can be retried, so processing the same completed task twice should not create duplicate assets. Streaming is another option for Lite and 4.x models. Set `stream: true` and request `application/x-ndjson`; the API emits partial success or failure events followed by one `image_generation.completed` event. Streaming cannot be combined with `async` or `callback_url`, so treat it as a separate UX choice rather than an extra flag on the same architecture. ## Step 4: Handle failure as part of the workflow Plan for `401 invalid_token`, `429 too_many_requests`, and `500 api_error`. Do not retry all failures equally: fix authentication errors, back off on rate limits, and use bounded retries for transient server failures. Log the returned `trace_id`, error `code`, and `message`, but never log the bearer token. That is enough for a durable first version: one endpoint, explicit model capabilities, an asynchronous task boundary, and traceable failures. I would build the smallest generate-edit loop first, observe real prompts and latency, and only then add streaming or multi-image features. The exact parameter reference and current model constraints are in the [Seedream Images API documentation](https://platform.acedata.cloud/documents/seedream-images-integration).