> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hy-Image-3.5 Preview Image Generation

> Text-to-image and up to 5 reference images, with 1K / 2K / 4K output or exact pixel dimensions. One image per request.

<Info>
  This endpoint is asynchronous. After submission, obtain the task ID from `data[0].task_id` and use [Task Query](/en/api-reference/tasks/status) to retrieve the status and image. Poll every 3–5 seconds with a recommended overall client timeout of 5 minutes. Stop at `completed` or `failed`.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "hy-image-v3.5-preview",
      "prompt": "A golden retriever running on a beach in warm evening light",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/images/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "hy-image-v3.5-preview",
          "prompt": "A golden retriever running on a beach in warm evening light",
          "size": "16:9",
          "resolution": "2K"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "hy-image-v3.5-preview",
      prompt: "A golden retriever running on a beach in warm evening light",
      size: "16:9",
      resolution: "2K"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer authentication: `Bearer <token>`, where `<token>` is your APIMart API Key.
</ParamField>

## Request parameters

<ParamField body="model" type="string" required>
  Must be `hy-image-v3.5-preview`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description for image generation or editing. Supports Chinese and English; must not be empty.
</ParamField>

<ParamField body="size" type="string" default="auto">
  Output aspect ratio or exact pixel dimensions.

  * Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
  * Exact pixels: for example, `2000x1104`, subject to the pixel limits below.
  * `auto` or omitted: the model chooses the ratio based on the prompt.

  With exact pixel dimensions, `resolution` does not determine the output dimensions.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Output resolution tier: `1K`, `2K`, or `4K`; default: `1K`.

  With exact pixel dimensions, this field does not determine the output dimensions. Always use a supported value; unsupported values return HTTP 400.
</ParamField>

<ParamField body="width" type="integer">
  Exact output width in pixels. Must be provided together with `height`; takes precedence over `size` and `resolution`.

  Width must be 256–8192, and width × height must not exceed 8,294,400. Multiples of 16 are recommended.
</ParamField>

<ParamField body="height" type="integer">
  Exact output height in pixels. Must be provided together with `width`.

  Height must be 256–8192, and width × height must not exceed 8,294,400. Multiples of 16 are recommended.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Public reference image URLs, up to 5 images. Omit for text-to-image; include for reference-based generation using the same endpoint.

  Supports JPEG, PNG, and WEBP. Each image should preferably be under 7MB. URLs must be publicly accessible.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Content you do not want in the image.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed; must be a non-negative integer. `0` or omission uses a random value.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Only one image is generated per request. Must be `1`; other values return HTTP 400.
</ParamField>

## Dimension selection

Priority: paired `width` / `height` → exact pixels in `size` → aspect ratio or `auto` in `size` combined with `resolution`.

For exact pixels, width and height must each be 256–8192, with no more than 8,294,400 pixels in total. Multiples of 16 are recommended for both.

### Exact pixel example

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}
```

You may instead omit `width` and `height` and pass `"size": "2000x1104"`.

### Reference image example

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "Make the car in the reference image red, preserving the original background and lighting",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "blur, text watermarks",
  "seed": 42,
  "n": 1
}
```

Replace example URLs with real publicly accessible image URLs. For multiple references, add URLs to `image_urls`, up to 5 images total.

## Submission response

<ResponseField name="code" type="integer">
  Response status code; `200` indicates success.
</ResponseField>

<ResponseField name="data" type="array">
  Task submission result.

  <Expandable title="Show task fields">
    <ResponseField name="status" type="string">
      `submitted` means submission succeeded, not that the image has been generated.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Task ID for querying status and results.
    </ResponseField>
  </Expandable>
</ResponseField>

## Query task results

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

Successful response example (the image URL is a placeholder):

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": ["https://example.com/generated-image.png"]
        }
      ]
    }
  }
}
```

* `pending` / `processing`: continue polling.
* `completed`: read the image URL from `data.result.images[0].url[0]`; `url` is an array of strings.
* `failed`: stop polling and read the reason from `data.error.message`. The charge is fully refunded. Prompt violations and content moderation failures also use this status.

Images are stored on the platform CDN. Download and save them before the time indicated by `expires_at` in the query result.

## Billing

Billed per image. See [Model Pricing](https://apimart.ai/pricing) for current prices.

* With an aspect ratio, billing follows the `resolution` tier.
* With exact pixel dimensions, the tier is determined by the shorter side:

| Tier | Shorter side |
| - | - |
| 1K | Up to 1024 pixels |
| 2K | 1025–2048 pixels |
| 4K | Over 2048 pixels |

Failed tasks receive a full refund.

## Common parameter errors

The following return HTTP 400 synchronously, without creating a task or charging:

| Issue | Action |
| - | - |
| Empty `prompt` | Provide a non-empty prompt |
| `n` is not `1` | Request only one image at a time |
| Negative `seed` | Use a non-negative integer; `0` means random |
| Unsupported `resolution` | Use `1K`, `2K`, or `4K` |
| Unsupported aspect ratio in `size` | Use one of the 10 ratios above or `auto` |
| Pixel dimensions out of range | Width and height must each be 256–8192; total pixels must not exceed 8,294,400 |
| More than 5 reference images | Reduce `image_urls` to at most 5 images |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.