On this page
Seedream API for Seedream 5.0 Pro
Use the Seedream API with the Seedream 5.0 Pro model to generate one image from a text prompt or up to ten public HTTPS reference images. Imya handles API authentication, asynchronous tasks, live credit billing, sanitized errors, and stored results.
REST API · v1 · Async tasks
What you can build
Use one REST workflow for prompt-based creation, reference-guided variations, and automated image generation.
Product and campaign images
Generate product scenes, advertising concepts, and branded visuals from a text prompt.
Reference-guided variations
Use 1-10 reference images to guide the subject, composition, or visual direction of a new result.
Automated image workflows
Submit asynchronously, poll a public task ID, and receive the finished image from Imya-managed storage.
Make your first Seedream API request
Create a task, keep its public task ID, then retrieve the task until it succeeds or fails.
- 1
Create an API key
Generate a key from your Imya account settings.
- 2
Choose an input
Use a prompt alone or add 1-10 reference images.
- 3
Retrieve the result
Poll the public task ID at most every 5 seconds.
Authentication and idempotency
Send your Imya API key as a Bearer token. Every generation POST also requires a unique Idempotency-Key so network retries cannot create another task or charge.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCreate an image generation
Omit image_urls for text-to-image. Add 1-10 public HTTPS images for reference-image generation. The server returns the live credits_reserved for this request.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-product-shot-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "A premium skincare bottle on pale stone, soft morning light",
"aspect_ratio": "4:3",
"quality": "basic",
"output_format": "png",
"n": 1
}'curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-edit-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "Keep the product shape and place it in a warm studio",
"image_urls": ["https://cdn.example.com/input/product.png"],
"aspect_ratio": "4:3",
"quality": "high",
"output_format": "jpeg",
"n": 1
}'Retrieve a task
Returns the latest state, final credit usage, stored image result, or a sanitized error. Poll at least 5 seconds apart; faster requests still count toward the rate limit but do not refresh upstream state.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Use seedream-5-pro. |
| prompt | string | Yes | Generation instructions, 3 to 3,000 characters. |
| image_urls | string[] | No | 1-10 public HTTPS reference images. Omit for text-to-image. |
| aspect_ratio | string | No | 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, or 3:2. Default: 1:1. |
| quality | string | No | basic or high. Default: basic. 16:9 and 9:16 support basic only. |
| output_format | string | No | png or jpeg. Default: png. |
| n | number | No | Must be 1. Exactly one image is generated. |
Responses
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:38.000Z",
"credits_reserved": 44,
"credits_used": 44,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}A new task returns HTTP 202. An exact idempotent replay returns HTTP 200 with Idempotent-Replayed: true. Successful images are copied to Imya-managed storage before the task becomes succeeded. Failed tasks can report generation_failed, refund_pending, or media_deleted.
Live credit billing
The base cost is 35 credits for both basic and high quality. The server applies the API key owner’s current plan coefficient. The example shows a regular account at 1.25×, rounded to 44 credits. Always use credits_reserved from the response. If a task remains unfinished for 30 minutes, Imya marks it failed and refunds eligible credits once without extending their original expiration date.
View credit plansTask status
pendingThe task was accepted and is waiting to start.
processingThe model is generating the image.
succeededGeneration finished and data contains the stored image.
failedGeneration failed. Read the sanitized error object.
Errors
400Missing Idempotency-Key or malformed JSON.
401Missing or invalid API key.
402The account does not have enough credits.
403The API account is disabled or the request is not allowed.
404The task was not found or does not belong to this account.
409The idempotency key was reused with a different body.
413The request body exceeds 64 KiB.
415Content-Type must be application/json.
422A model parameter, prompt, or reference image is invalid.
429The API key reached its rate or concurrency limit.
5xxThe request could not be completed. Check the task before creating a new request.
Shared Imya API contract
These rules apply to every public image and video generation endpoint. Model-specific fields and prices remain in the parameter table above.
Billing and safe retries
The exact credits shown in credits_reserved are deducted atomically when a new task is accepted. Replaying the same Idempotency-Key and request body returns the original task without a second charge.
Timeouts and refunds
A task that has not reached a terminal result within 30 minutes fails. Eligible credits are refunded once, and the refund keeps the original credit expiration date.
Rate and concurrency limits
Each API key can make up to 120 requests per 60 seconds. One account can run up to five image tasks or three video tasks at the same time. A 429 response may include Retry-After guidance; honor it when present.
Polling and task ownership
Poll GET /v1/tasks/{id} at least five seconds apart, using the id returned by task creation. Faster requests still count toward the API-key rate limit and do not refresh upstream state. Only the account that created a task can retrieve it. Webhooks, SDKs, and batch submission are not currently available.
Errors and content safety
Public errors are sanitized and never expose upstream credentials, internal URLs, or infrastructure details. Unsafe prompts can be rejected with prompt_blocked before generation starts.
Image result retention
Stored image results remain available for seven days on free accounts and up to 30 days on active paid or Lifetime accounts. After deletion, the response has status failed and error.code media_deleted instead of an empty success.
Seedream API production integration guide
Treat a reliable Seedream 5.0 Pro integration as a small asynchronous job system, not one long-running HTTP request. Persist the id returned for every Imya task and make retries deterministic. These practices cover production decisions.
Choose parameters from the model contract
Validate every request against this page's parameter table. During development, begin with the smallest supported input and output settings, then increase quality, dimensions, duration, or reference count only when the product requires it. Check user-provided prompt length, file type, and file size before calling the API.
For reference-image workflows, preserve the reference order and make sure the user has permission to use every uploaded image.
Design the asynchronous workflow for recovery
Submit the image task, store its returned id with your job record, and let a background worker retrieve status. Poll GET /v1/tasks/{id} at least five seconds apart. Faster requests still count toward the API-key rate limit but do not refresh upstream state. The public status is pending, processing, succeeded, or failed. Stop at a terminal state or the hard 30-minute deadline. Imya does not currently provide webhooks, SDKs, or batch submission, so integrate through direct HTTP requests and polling.
- 01Persist id, status, credits_reserved, and the request identity before updating the UI.
- 02Back off after transient network errors, respect Retry-After on 429 responses, and never turn a transport error into a new paid task automatically.
- 03Limit work per account: up to five concurrent image tasks. Each API key also has a limit of 120 requests per 60 seconds.
Make billing and retries deterministic
When a new task is accepted, the exact credits_reserved amount is deducted atomically. Generate one Idempotency-Key for each intended creation and save it with the request. Replaying that key with the same body returns the original task without another charge. A changed request needs a new key.
For an eligible failed task, Imya refunds credits once and preserves their original expiration date. The public status remains failed: error.code is refund_pending while settlement is processing, and credits_refunded appears when settlement completes. Reconcile by id; never issue credits in the client.
Protect credentials, ownership, and generated media
Keep API keys on your server, never in browser or mobile bundles. Associate each returned id with its authenticated user or workspace and verify ownership before displaying a result. Log request and task IDs for support without exposing prompts, private media URLs, or credentials.
Image results remain available for seven days on free accounts and up to 30 days on active paid or Lifetime accounts. After removal, the response has status failed and error.code media_deleted. Copy required results into storage you control, with user consent and a clear privacy policy.
Production checklist
- Validate model-specific fields before submitting.
- Store one idempotency key and body per intended task.
- Persist state and poll at least five seconds apart.
- Enforce account concurrency and key rate limits.
- Handle the four public statuses explicitly; for failed responses, inspect error.code for media_deleted or refund_pending and credits_refunded for a completed refund.
- Keep credentials server-side and define result retention.
Common questions
How often should my worker poll?
Wait at least five seconds; use slower backoff while processing continues.
When are credits charged?
The exact credits_reserved amount is deducted atomically when a new task is accepted.
Can a retry charge twice?
Not when the same Idempotency-Key and identical body are replayed; the original task returns.
How should I handle terminal failure?
Show a clear error, retain id, and let the server complete any eligible one-time refund. Inspect credits_refunded instead of waiting for a separate refunded status.
Ready to build?
Create an Imya API key for your first request, or test prompts, reference images, and quality settings in the hosted generator before integrating.