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

# 文生图

> GPT Image 2 文生图 —— 基于文本提示生成图像（OpenAI 兼容接口）

使用 GPT Image 2 从文本生成图像。上游是同步接口；平台仍然走标准的 submit / query / webhook 异步任务流程。

### 可用模型

`gpt-image-2/text-to-image`

### 价格

按 **分辨率档位 × 张数** 计费，失败不扣费：

| `resolution` | 单价 / 张     |
| ------------ | ---------- |
| `1k`（默认）     | **\$0.02** |
| `2k`         | **\$0.04** |
| `4k`         | **\$0.06** |

总费用 = `n × 单价(resolution)`。

<ParamField body="model" type="string" required>
  `gpt-image-2/text-to-image`
</ParamField>

<ParamField body="callBackUrl" type="string">
  Webhook 回调地址。
</ParamField>

<ParamField body="input" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ParamField body="prompt" type="string" required>
      生成图像的文本描述。
    </ParamField>

    <ParamField body="ratio" type="string">
      图像宽高比。13 个可选值：

      `1:1` / `3:2` / `2:3` / `4:3` / `3:4` / `5:4` / `4:5` / `16:9` / `9:16` / `2:1` / `1:2` / `21:9` / `9:21`

      默认由上游决定。

      <Warning>
        当 `resolution = 4k` 时，`ratio` 仅支持 `16:9` / `9:16` / `2:1` / `1:2` / `21:9` / `9:21`。其他比例 + 4K 因总像素超上限会被拒绝。
      </Warning>
    </ParamField>

    <ParamField body="resolution" type="string">
      输出分辨率档位。可选 `1k` / `2k` / `4k`。

      `1k` 是默认值；不传等同 `1k`。

      `ratio × resolution` → 实际像素：

      | ratio  | `1k`      | `2k`      | `4k`      |
      | ------ | --------- | --------- | --------- |
      | `1:1`  | 1024×1024 | 2048×2048 | ❌         |
      | `3:2`  | 1536×1024 | 2048×1360 | ❌         |
      | `2:3`  | 1024×1536 | 1360×2048 | ❌         |
      | `4:3`  | 1024×768  | 2048×1536 | ❌         |
      | `3:4`  | 768×1024  | 1536×2048 | ❌         |
      | `5:4`  | 1280×1024 | 2560×2048 | ❌         |
      | `4:5`  | 1024×1280 | 2048×2560 | ❌         |
      | `16:9` | 1536×864  | 2048×1152 | 3840×2160 |
      | `9:16` | 864×1536  | 1152×2048 | 2160×3840 |
      | `2:1`  | 2048×1024 | 2688×1344 | 3840×1920 |
      | `1:2`  | 1024×2048 | 1344×2688 | 1920×3840 |
      | `21:9` | 2016×864  | 2688×1152 | 3840×1648 |
      | `9:21` | 864×2016  | 1152×2688 | 1648×3840 |
    </ParamField>

    <ParamField body="n" type="integer">
      生成张数。范围 `1-10`，默认 `1`。账单按 `n × 单价(resolution)` 线性扣费。
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```bash 默认（1K） theme={null}
  curl --request POST \
    --url https://api.maxapi.io/api/v1/task/submit \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-image-2/text-to-image",
    "callBackUrl": "https://example.com/webhook",
    "input": {
      "prompt": "一只乌鸦在霓虹街道上奔跑",
      "ratio": "16:9",
      "n": 1
    }
  }'
  ```

  ```bash 4K 输出 theme={null}
  curl --request POST \
    --url https://api.maxapi.io/api/v1/task/submit \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-image-2/text-to-image",
    "callBackUrl": "https://example.com/webhook",
    "input": {
      "prompt": "星空下的古老城堡",
      "ratio": "16:9",
      "resolution": "4k",
      "n": 1
    }
  }'
  ```

  ```bash 批量 (n=4, 2K) theme={null}
  curl --request POST \
    --url https://api.maxapi.io/api/v1/task/submit \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-image-2/text-to-image",
    "callBackUrl": "https://example.com/webhook",
    "input": {
      "prompt": "水彩画风格的橘猫",
      "ratio": "1:1",
      "resolution": "2k",
      "n": 4
    }
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 提交成功 theme={null}
  {
    "code": 0,
    "msg": "ok",
    "data": {
      "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
  ```
</ResponseExample>

***

## 获取结果

通过 [Query Task](/cn/api-reference/query-task) 或 Webhook 获取结果。

```json theme={null}
{
  "code": 0,
  "msg": "ok",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "SUCCESS",
    "input": {
      "model": "gpt-image-2/text-to-image",
      "prompt": "一只乌鸦在霓虹街道上奔跑"
    },
    "result": {
      "type": "image",
      "urls": ["https://cdn.maxapi.io/images/.../image-0.png"]
    }
  }
}
```

<Note>
  最终 `urls` 为 Max API CDN 上的稳定地址，可直接访问。`n > 1` 时数组会包含多张图。
</Note>