# Seedream 5.0 Pro API Reference

Create one Seedream 5.0 Pro image from a text prompt and optional reference images through the Imya REST API.

> Production Beta: the v1 endpoint is callable. Use an idempotency key for each logical generation request and poll the returned task until it succeeds or fails.

## Base URL

```text
https://imya.ai
```

## Authentication and idempotency

Create an API key in your Imya account and pass it as a Bearer token. Every generation POST also requires an idempotency key.

```http
Authorization: Bearer imya_xxxxxxxxx
Content-Type: application/json
Idempotency-Key: your-unique-request-id
```

Use a new idempotency key for every logical generation. Retrying the same request with the same key returns the original task instead of creating and charging for another task. A key may contain 1-128 ASCII letters, numbers, dots, colons, underscores, or hyphens.

## Create an image generation task

```http
POST /v1/images/generations
```

Omit `image_urls` for text-to-image. Include one or more reference images for image-to-image.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | Use `seedream-5-pro`. |
| prompt | string | Yes | Generation instructions, from 3 to 5,000 characters. |
| image_urls | string[] | No | 1 to 10 public HTTPS reference images. |
| aspect_ratio | string | No | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, or `21:9`. Default is `1:1`. |
| quality | string | No | `basic` or `high`. Default is `basic`. |
| output_format | string | No | `png` or `jpeg`. Default is `png`. |
| n | number | No | Must be `1`. Exactly one image is generated. |

### Text-to-image example

```bash
curl 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, editorial product photography",
    "aspect_ratio": "4:3",
    "quality": "basic",
    "output_format": "png",
    "n": 1
  }'
```

### Reference-image example

```bash
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 change the setting to a warm studio with soft shadows",
    "image_urls": ["https://cdn.example.com/input/product.png"],
    "aspect_ratio": "4:3",
    "quality": "high",
    "output_format": "jpeg",
    "n": 1
  }'
```

### Accepted response

```json
{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "pending",
  "model": "seedream-5-pro",
  "credits_reserved": 44
}
```

The example shows a regular account: a 35-credit base cost with the current 1.25 account coefficient, rounded to 44 credits. Always use the live `credits_reserved` returned by the server; do not calculate or cache the final charge in your client.

## Retrieve a task

```http
GET /v1/tasks/{task_id}
```

Poll no faster than once every 5 seconds.

### Example request

```bash
curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer YOUR_IMYA_API_KEY"
```

### Completed response

```json
{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "model": "seedream-5-pro",
  "credits_used": 44,
  "data": [
    {
      "url": "https://cdn.imya.ai/generated/example.png"
    }
  ]
}
```

Successful image results are copied to Imya-managed storage before the task becomes `succeeded`. Download or copy results according to your application's retention needs. If a stored asset has already been removed by retention or deletion, the task can return `media_deleted`.

## Status and HTTP behavior

| Status | Meaning |
| --- | --- |
| pending | The task has been accepted. |
| processing | The model is generating. |
| succeeded | The result is ready in `data`. |
| failed | The task failed. Inspect the sanitized `error` object. |

A new task returns HTTP `202`. Replaying the same body and idempotency key returns HTTP `200` with `Idempotent-Replayed: true`. Task retrieval returns HTTP `200`. A failed task can report `generation_failed`, `refund_pending`, or `media_deleted` in `error.code`.

## Credit billing, timeout, and refunds

Seedream 5.0 Pro has a 35-credit base cost for both `basic` and `high` quality. The server applies the API key owner's current plan coefficient and returns the live amount as `credits_reserved`. A successful task reports the final debit as `credits_used`.

If a task does not reach a terminal state within 30 minutes, Imya marks it failed. Eligible reserved credits are released or refunded once. Promotional and reward credits keep their original expiration date, so already expired credits are not reactivated. If automatic settlement still needs attention, the task reports `refund_pending` rather than claiming that a refund is complete.

## Errors

| Code | Meaning |
| --- | --- |
| 400 | Missing or invalid idempotency key or malformed JSON. |
| 401 | Missing or invalid API key. |
| 402 | Not enough credits. |
| 403 | The API account is disabled or the request is not allowed. |
| 409 | The idempotency key was already used with a different request body. |
| 413 | The request body exceeds 64 KiB. |
| 422 | Invalid model, prompt, image URL, aspect ratio, quality, output format, or n. |
| 429 | Rate or concurrent-task limit reached. |
| 5xx | The request could not be completed or submitted. Check the task before retrying with a different idempotency key. |