> ## 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 回につき 1 枚生成。

<Info>
  非同期 API です。送信後、`data[0].task_id` からタスク ID を取得し、[タスク照会](/ja/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": "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>

## リクエストヘッダー

<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 枚。省略時はテキストから生成し、指定時は同じ API で参照画像から生成します。

  JPEG、PNG、WEBP に対応。1 枚あたり 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 枚のみ生成。`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": "A minimalist seaside travel poster with a warm sunset",
  "width": 2000,
  "height": 1104
}
```

`width` と `height` を省略し、代わりに `"size": "2000x1104"` を指定することもできます。

### 参照画像による生成例

```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
}
```

サンプル URL を実際に公開アクセス可能な画像 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 を取得。`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 回に 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.