> ## 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 图像生成

> 支持文生图、最多 5 张参考图、1K / 2K / 4K 输出及精确像素尺寸，每次生成 1 张图片。

<Info>
  本接口采用异步处理。提交成功后，从 `data[0].task_id` 获取任务 ID，通过 [任务查询](/cn/api-reference/tasks/status) 获取状态和图片。建议每 3–5 秒轮询一次，客户端整体等待超时设为 5 分钟；状态为 `completed` 或 `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": "画一只在沙滩上奔跑的金毛犬，傍晚的暖色光",
      "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": "画一只在沙滩上奔跑的金毛犬，傍晚的暖色光",
          "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: "画一只在沙滩上奔跑的金毛犬，傍晚的暖色光",
      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>

## 请求头

<ParamField header="Authorization" type="string" required>
  Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  固定为 `hy-image-v3.5-preview`。
</ParamField>

<ParamField body="prompt" type="string" required>
  图片生成或编辑的文本描述，支持中文和英文，不能为空。
</ParamField>

<ParamField body="size" type="string" default="auto">
  输出宽高比或精确像素尺寸。

  * 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`。
  * 精确像素：例如 `2000x1104`，须满足下方像素限制。
  * `auto` 或不传：由模型根据提示词决定比例。

  使用精确像素时，`resolution` 不参与尺寸选择。
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  输出分辨率档位：`1K`、`2K` 或 `4K`，默认 `1K`。

  指定精确像素尺寸时，此字段不参与尺寸选择。请始终使用上述支持的值，不支持的值会返回 HTTP 400。
</ParamField>

<ParamField body="width" type="integer">
  精确输出宽度，单位为像素。必须与 `height` 成对传入，优先级高于 `size` 和 `resolution`。

  宽度须在 256–8192 之间，且宽 × 高不超过 8,294,400；建议使用 16 的倍数。
</ParamField>

<ParamField body="height" type="integer">
  精确输出高度，单位为像素。必须与 `width` 成对传入。

  高度须在 256–8192 之间，且宽 × 高不超过 8,294,400；建议使用 16 的倍数。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片的公网 URL 列表，最多 5 张。不传为文生图，传入则为参考图生图，使用同一接口。

  图片支持 JPEG、PNG、WEBP，单张建议小于 7MB。URL 必须可从公网访问。
</ParamField>

<ParamField body="negative_prompt" type="string">
  不希望出现在图片中的内容。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子，必须为非负整数。传 `0` 或不传时随机生成。
</ParamField>

<ParamField body="n" type="integer" default="1">
  每次只生成 1 张图片，只能传 `1`。其他值会返回 HTTP 400。
</ParamField>

## 尺寸选择

尺寸参数优先级：成对的 `width` / `height` → `size` 精确像素 → `size` 宽高比或 `auto` 搭配 `resolution`。

精确像素的宽、高各为 256–8192，总像素不超过 8,294,400。建议宽、高均取 16 的倍数。

### 精确像素示例

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "简洁的海边旅行海报，暖色夕阳",
  "width": 2000,
  "height": 1104
}
```

也可以省略 `width`、`height`，改为传入 `"size": "2000x1104"`。

### 参考图生成示例

```json theme={null}
{
  "model": "hy-image-v3.5-preview",
  "prompt": "将参考图中的汽车改为红色，保留原有背景和光照",
  "image_urls": ["https://example.com/car.png"],
  "size": "16:9",
  "resolution": "2K",
  "negative_prompt": "模糊、文字水印",
  "seed": 42,
  "n": 1
}
```

请将示例 URL 替换为实际可公开访问的图片地址。多图参考时在 `image_urls` 中添加地址，总数不超过 5 张。

## 提交响应

<ResponseField name="code" type="integer">
  响应状态码，成功为 `200`。
</ResponseField>

<ResponseField name="data" type="array">
  任务提交结果。

  <Expandable title="显示任务字段">
    <ResponseField name="status" type="string">
      提交成功时为 `submitted`，不代表图片已生成。
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务 ID，用于查询状态和结果。
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询任务结果

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

成功响应示例（图片 URL 为占位示例）：

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

* `pending` / `processing`：继续轮询。
* `completed`：从 `data.result.images[0].url[0]` 获取图片地址，`url` 为字符串数组。
* `failed`：停止轮询，从 `data.error.message` 获取原因，费用全额退回。提示词违规或内容审核不通过也按失败处理。

图片已转存平台 CDN，请在查询结果的 `expires_at` 指定时间前下载保存。

## 计费说明

按张计费，具体价格以[模型定价](https://apimart.ai/pricing)为准。

* 使用宽高比时，按 `resolution` 档位收费。
* 使用精确像素时，按图片短边确定档位：

| 档位 | 短边范围 |
| - | - |
| 1K | 不超过 1024 像素 |
| 2K | 1025–2048 像素 |
| 4K | 超过 2048 像素 |

任务失败时全额退款。

## 常见参数错误

以下情况同步返回 HTTP 400，不创建任务、不扣费：

| 情况 | 处理方式 |
| - | - |
| `prompt` 为空 | 提供非空提示词 |
| `n` 不为 `1` | 每次只请求 1 张图片 |
| `seed` 为负数 | 使用非负整数；`0` 表示随机 |
| `resolution` 不受支持 | 使用 `1K`、`2K` 或 `4K` |
| `size` 宽高比不受支持 | 使用上方列出的 10 种比例或 `auto` |
| 精确像素越界 | 宽、高各为 256–8192，且总像素不超过 8,294,400 |
| 参考图超过 5 张 | 将 `image_urls` 减少至最多 5 张 |


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