# ImageTo API 接入说明

> 版本：2026-09-19  
> 基础地址：`https://image.own-jarvis.com`

ImageTo 提供文生图、图生图和批量并发生成能力。单张图片可使用同步接口直接取得最终 URL；批量或需要断线恢复时，可使用异步任务接口创建后查询结果。

## 一、快速接入

1. 在 [ImageTo 控制台](https://image.own-jarvis.com) 使用手机号和短信验证码注册；新注册账号赠送 1 积分，积分不足时可进入「积分充值」。
2. 进入「API 文档」创建并复制 API Key。
3. 立即保存完整密钥；完整密钥只显示一次。
4. 调用 `GET /v1/models` 获取当前可用模型和该账户的每张积分。
5. 可先调用 `GET /v1/account/balance` 检查当前可用积分和密钥状态。
6. 单张直返调用 `POST /v1/images/generations`；批量调用 `POST /v1/images/tasks`。
7. 同步接口直接读取 `data[0].url`；异步接口使用任务 ID 查询 `GET /v1/images/tasks/{task_id}`。

如果需要参考图片，可以先调用 `POST /v1/files` 上传，也可以在创建任务时直接传入公网图片 URL。

## 二、认证方式

所有 API 请求都需要在请求头中携带客户独立 API Key：

```http
Authorization: Bearer itx_你的客户密钥
```

请只在服务端保存和调用 API Key，不要把密钥写进网页、App 安装包或公开代码仓库。密钥泄露后，请立即在控制台停用并重新创建。

## 三、查询账户余额

接口：`GET /v1/account/balance`

建议在提交任务前查询一次，或者在生成程序出现异常时用于检查当前可用积分、API Key 是否有效以及账户倍率。该接口不会扣除积分。

### 请求

```bash
curl 'https://image.own-jarvis.com/v1/account/balance' \
  -H 'Authorization: Bearer itx_你的客户密钥'
```

### 成功响应

HTTP 状态码：`200 OK`

```json
{
  "object": "account.balance",
  "data": {
    "balance": "12.3456",
    "unit": "points",
    "points_per_cny": "1.0000",
    "account_status": "active",
    "billing_multiplier": "1.0000",
    "api_key_prefix": "itx_abcd1234",
    "checked_at": "2026-09-17T02:30:00+00:00"
  }
}
```

- `balance` 是当前可用积分，使用四位小数字符串；积分为 `0.0000` 时接口仍返回成功。
- `account_status` 正常情况下为 `active`。
- `billing_multiplier` 是该账户当前计费倍率。
- `api_key_prefix` 仅返回密钥前缀，便于确认程序使用的是哪一把 Key，不会返回完整密钥。
- API Key 缺失、无效、已停用，或者账户已停用时，返回 HTTP `401` 和错误码 `INVALID_API_KEY`。

## 四、查询可用模型

接口：`GET /v1/models`

返回当前管理员已启用的全部模型、展示名称、画面比例、参考图上限，以及该 API Key 所属账户的实际每张积分。该接口不扣积分。被停用的模型不会出现在列表中；如果继续用已停用的模型 ID 提交新任务，会返回 HTTP `503` 和错误码 `MODEL_DISABLED`。

### 请求

```bash
curl 'https://image.own-jarvis.com/v1/models' \
  -H 'Authorization: Bearer itx_你的客户密钥'
```

### 成功响应

HTTP 状态码：`200 OK`

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "owned_by": "imageto",
      "display_name": "GPT-image 2.0 · 标准清晰度",
      "description": "GPT-image 2.0 经典线路，适合日常快速出图",
      "tier": "1K",
      "price_points": "0.0525",
      "billing_unit": "per_generation",
      "max_reference_images": 10,
      "supported_aspect_ratios": [
        "auto", "1:1", "3:2", "2:3", "4:3", "3:4",
        "4:5", "5:4", "16:9", "9:16", "21:9", "9:21"
      ],
      "capabilities": {
        "text_to_image": true,
        "image_to_image": true,
        "synchronous": true,
        "asynchronous": true
      }
    }
  ],
  "unit": "points",
  "points_per_cny": "1.0000",
  "has_more": false
}
```

- `id` 是提交生成任务时的 `model` 值。
- `price_points` 是当前账户生成一张图片实际使用的积分价格。
- `supported_aspect_ratios` 是该模型可用的画面比例；提交任务时应从该列表中选择。
- `max_reference_images` 是该模型单次允许的参考图数量上限。
- API Key 缺失、无效或已停用时，返回 HTTP `401` 和错误码 `INVALID_API_KEY`。

## 五、可用模型参考表

| 模型 ID | 输出档位 | 每张消耗积分 | 适用场景 |
| --- | --- | ---: | --- |
| `gpt-image-2` | GPT-image 2.0 标准 1K | 0.0525 积分 / 张 | 日常快速出图 |
| `gpt-image-2-2k` | GPT-image 2.0 标准 2K | 0.0675 积分 / 张 | 更高分辨率输出 |
| `gpt-image-2-4k` | GPT-image 2.0 标准 4K | 0.0825 积分 / 张 | 大尺寸和高精度交付 |
| `gpt-image-2.5` | GPT-image 2.5 标准 1K | 0.0525 积分 / 张 | GPT-image 2.5 标准系列 |
| `gpt-image-2.5-2k` | GPT-image 2.5 标准 2K | 0.0675 积分 / 张 | GPT-image 2.5 标准系列 |
| `gpt-image-2.5-4k` | GPT-image 2.5 标准 4K | 0.0825 积分 / 张 | GPT-image 2.5 标准系列 |
| `gpt-image-2.5-flare` | GPT-image 2.5 Flare 1K | 0.1050 积分 / 张 | GPT-image 2.5 Flare 系列 |
| `gpt-image-2.5-flare-2k` | GPT-image 2.5 Flare 2K | 0.1200 积分 / 张 | GPT-image 2.5 Flare 系列 |
| `gpt-image-2.5-flare-4k` | GPT-image 2.5 Flare 4K | 0.1350 积分 / 张 | GPT-image 2.5 Flare 系列 |
| `gpt-image-2.5-sunburst` | GPT-image 2.5 Sunburst 1K | 0.1050 积分 / 张 | GPT-image 2.5 Sunburst 系列 |
| `gpt-image-2.5-sunburst-2k` | GPT-image 2.5 Sunburst 2K | 0.1200 积分 / 张 | GPT-image 2.5 Sunburst 系列 |
| `gpt-image-2.5-sunburst-4k` | GPT-image 2.5 Sunburst 4K | 0.1350 积分 / 张 | GPT-image 2.5 Sunburst 系列 |
| `special-gpt-image-2.5` | GPT-image 2.5 特价渠道 标准 1K | 0.0450 积分 / 张 | 第二供应商特价线路 |
| `special-gpt-image-2.5-flare` | GPT-image 2.5 特价渠道 Flare 1K | 0.0675 积分 / 张 | 第二供应商 Flare 特价线路 |
| `special-gpt-image-2.5-sunburst` | GPT-image 2.5 特价渠道 Sunburst 1K | 0.1350 积分 / 张 | 第二供应商 Sunburst 特价线路 |
| `grok-imagine-image` | Grok Imagine 1K | 0.0600 积分 / 张 | 快速生成与编辑 |
| `grok-imagine-image-2.0` | Grok Imagine 2.0 1K | 0.0750 积分 / 张 | 2.0 标准输出 |
| `grok-imagine-image-2.0-2k` | Grok Imagine 2.0 2K | 0.0825 积分 / 张 | 2.0 高清输出 |
| `grok-imagine-image-2.0-slow` | Grok Imagine 2.0 经济版 | 0.0450 积分 / 张 | 慢速低成本任务 |
| `grok-imagine-image-quality` | Grok Imagine Quality 1K | 0.0900 积分 / 张 | 高质量历史线路；请预留迁移 |

以上是基础积分消耗；若商务合同为账户设置了更高倍率，以控制台实际显示积分为准。平台兑换比例为 1 元 = 1 积分。

## 六、画面比例

支持以下 `aspect_ratio`：

| 类型 | 可选值 |
| --- | --- |
| 自动 | `auto` |
| 方形 | `1:1` |
| 横向 | `3:2`、`4:3`、`5:4`、`16:9`、`21:9` |
| 竖向 | `2:3`、`3:4`、`4:5`、`9:16`、`9:21` |

使用 `auto` 时，平台会交由上游选择兼容性最好的比例。
特价渠道的 3 个模型不支持 `9:21`，控制台会自动禁用该选项。
Grok Imagine 系列支持 `auto`、`1:1`、`3:2`、`2:3`、`4:3`、`3:4`、`16:9`、`9:16`；单次最多 5 张参考图。

> 兼容性提示：上游厂商已公告 `grok-imagine-image-quality` 将在 2026-11-02 退休。新项目建议优先使用 `grok-imagine-image-2.0`。

## 七、上传参考图片

### 请求

```bash
curl -X POST 'https://image.own-jarvis.com/v1/files' \
  -H 'Authorization: Bearer itx_你的客户密钥' \
  -H 'X-File-Name: source.png' \
  -H 'Content-Type: image/png' \
  --data-binary '@source.png'
```

上传接口接收图片二进制内容，不是 `multipart/form-data`。支持 JPG、PNG、WebP、GIF，单张不超过 20MB。

如果文件名包含中文，建议先进行 URL 编码，再放入 `X-File-Name` 请求头。

### 成功响应

HTTP 状态码：`201 Created`

```json
{
  "object": "file",
  "data": {
    "id": "54a6c984-ef98-4d33-bc9f-8bbd0cb23f58",
    "name": "source.png",
    "mime_type": "image/png",
    "size": 248631,
    "url": "https://oss.own-jarvis.com/n8n/uploads/2026/08/54a6c984-ef98-4d33-bc9f-8bbd0cb23f58/source.png",
    "provider": "oss",
    "retained": false,
    "created_at": "2026-08-05T02:00:00+00:00",
    "expires_at": "2026-08-06T02:00:00+00:00"
  }
}
```

生产环境上传的参考图片会持久化到 OSS，实际 OSS/CDN 地址以 `data.url` 为准。保存 `data.id`，在创建任务时传入 `upload_ids`。一次任务通常最多使用 10 张参考图；特价渠道模型最多 8 张。`upload_ids` 与 `image_urls` 的数量合计不能超过当前模型上限。

## 八、创建异步图片任务

接口：`POST /v1/images/tasks`

### 请求字段

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 否 | `gpt-image-2` | 模型 ID，建议明确传入 |
| `prompt` | string | 是 | — | 图片提示词，1–5000 个字符 |
| `aspect_ratio` | string | 否 | `auto` | 画面比例 |
| `upload_ids` | string[] | 否 | `[]` | 通过 `/v1/files` 获得的文件 ID；与 `image_urls` 合计最多 10 张 |
| `image_urls` | string[] | 否 | `[]` | 可公开访问的 HTTP(S) 图片 URL；与 `upload_ids` 合计最多 10 张 |
| `count` | integer | 否 | `1` | 生成张数，API 范围为 1–20 |

不传参考图时为文生图；`upload_ids` 或 `image_urls` 至少有一项时自动切换为图生图。

### 文生图示例

```bash
curl -X POST 'https://image.own-jarvis.com/v1/images/tasks' \
  -H 'Authorization: Bearer itx_你的客户密钥' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260805-0001' \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张高端咖啡品牌海报，深绿色背景，金色中文标题：今日特调，棚拍质感",
    "aspect_ratio": "3:4",
    "upload_ids": [],
    "image_urls": [],
    "count": 1
  }'
```

### 使用已上传图片进行图生图

```bash
curl -X POST 'https://image.own-jarvis.com/v1/images/tasks' \
  -H 'Authorization: Bearer itx_你的客户密钥' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260805-0002' \
  -d '{
    "model": "gpt-image-2-2k",
    "prompt": "保留人物五官、发型和姿势，把服装改成深红色丝绒礼服，电影级柔光",
    "aspect_ratio": "2:3",
    "upload_ids": ["54a6c984-ef98-4d33-bc9f-8bbd0cb23f58"],
    "image_urls": [],
    "count": 1
  }'
```

### 使用公网图片 URL 进行图生图

```json
{
  "model": "gpt-image-2",
  "prompt": "保持产品外观不变，替换成干净的白色影棚背景",
  "aspect_ratio": "1:1",
  "upload_ids": [],
  "image_urls": ["https://cdn.example.com/product.jpg"],
  "count": 1
}
```

公网图片必须能被平台和上游服务直接访问，不能要求登录、Cookie 或临时内网权限。

### 批量并发生成

将 `count` 设置为 2–20 即可创建批量任务：

```bash
curl -X POST 'https://image.own-jarvis.com/v1/images/tasks' \
  -H 'Authorization: Bearer itx_你的客户密钥' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: campaign-20260805-batch-01' \
  -d '{
    "model": "gpt-image-2-4k",
    "prompt": "东方美学香水广告，水墨山峦和晨雾，产品居中，画面无人物",
    "aspect_ratio": "16:9",
    "upload_ids": [],
    "image_urls": [],
    "count": 3
  }'
```

多张任务会原子创建并并发执行：

- 提交时一次性检查整批积分；积分不足时不会创建部分任务。
- 每张图片都有独立任务 ID、状态、结果和积分账单。
- 某一张失败只退回该张预占积分，不影响其他图片继续生成。
- 当前平台最多 8 路并发；超过并发数的任务会自动排队。

### 单张创建响应

首次创建成功返回 `202 Accepted`：

```json
{
  "object": "image.task",
  "data": {
    "id": "cd9db50e-a246-4945-ad62-c6826c575c1d",
    "model": "gpt-image-2",
    "model_label": "GPT-image 2.0 · 标准清晰度",
    "mode": "text_to_image",
    "status": "queued",
    "stage": "queued",
    "progress": 0,
    "aspect_ratio": "3:4",
    "usage": {"total_tokens": 0},
    "billing": {
      "currency": "CNY",
      "display_unit": "points",
      "reserved_amount": "0.0525",
      "amount": "0.0000",
      "settled": false
    },
    "batch": {"id": null, "index": 1, "count": 1},
    "created_at": "2026-08-05T02:10:00+00:00",
    "updated_at": "2026-08-05T02:10:00+00:00",
    "finished_at": null
  }
}
```

### 批量创建响应

```json
{
  "object": "image.batch",
  "data": {
    "batch_id": "256b5a7f-3e45-4d29-819b-c6c234f8a4ac",
    "count": 3,
    "tasks": [
      {"id": "任务ID-1", "status": "queued", "batch": {"index": 1, "count": 3}},
      {"id": "任务ID-2", "status": "queued", "batch": {"index": 2, "count": 3}},
      {"id": "任务ID-3", "status": "queued", "batch": {"index": 3, "count": 3}}
    ]
  }
}
```

实际响应中的每个 `tasks` 项还会包含模型、进度、账单和时间等完整字段。请保存数组内的所有任务 ID，并分别查询。

## 九、同步生成（无需轮询）

接口：`POST /v1/images/generations`

请求字段与异步创建接口相同，但 `count` 必须是 `1`。连接会一直保持到图片生成完成并保存到 ImageTo OSS，然后直接返回最终图片 URL。

```bash
curl -X POST 'https://image.own-jarvis.com/v1/images/generations' \
  -H 'Authorization: Bearer itx_你的客户密钥' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-sync-20260909-0001' \
  --max-time 900 \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "参考这些图片的配色，生成一张简洁的品牌主视觉",
    "aspect_ratio": "1:1",
    "upload_ids": [],
    "image_urls": ["https://cdn.example.com/reference-1.png"],
    "count": 1
  }'
```

成功返回 HTTP `200`：

```json
{
  "created": 1788969600,
  "model": "gpt-image-2.5",
  "task_id": "cd9db50e-a246-4945-ad62-c6826c575c1d",
  "data": [
    {"url": "https://your-result-cdn.example.com/image.png"}
  ],
  "usage": {"total_tokens": 2654},
  "billing": {
    "currency": "CNY",
    "display_unit": "points",
    "reserved_amount": "0.0525",
    "amount": "0.0525",
    "settled": true
  }
}
```

请将调用端、反向代理和网关的读取超时设为至少 900 秒。连接意外中断不会取消已经创建的任务；使用相同 `Idempotency-Key` 重试可避免重复生成和重复扣除积分，任务也会保留在控制台「调用记录」中。

同步接口生成失败时返回 HTTP `502` 并自动退回积分；平台等待达到上限时返回 HTTP `504` 和 `task_id`，该任务仍会在后台继续，可用异步查询接口或控制台历史记录查看最终结果。

## 十、查询异步任务

接口：`GET /v1/images/tasks/{task_id}`

```bash
curl 'https://image.own-jarvis.com/v1/images/tasks/cd9db50e-a246-4945-ad62-c6826c575c1d' \
  -H 'Authorization: Bearer itx_你的客户密钥'
```

### 任务状态

| `status` | 含义 | 是否继续查询 |
| --- | --- | --- |
| `queued` | 已进入队列 | 是 |
| `running` | 正在生成或保存 | 是 |
| `succeeded` | 已成功 | 否 |
| `failed` | 已失败，预占积分已退回 | 否 |

建议前台页面每 2–5 秒查询一次；页面进入后台后可降低至每 10–15 秒一次。不要在任务已经结束后继续高频查询。

### 成功响应

```json
{
  "object": "image.task",
  "data": {
    "id": "cd9db50e-a246-4945-ad62-c6826c575c1d",
    "status": "succeeded",
    "stage": "completed",
    "progress": 100,
    "result": {
      "url": "https://your-result-cdn.example.com/image.png",
      "mime_type": "image/png",
      "provider": "oss",
      "persistent": true
    },
    "billing": {
      "currency": "CNY",
      "display_unit": "points",
      "reserved_amount": "0.0525",
      "amount": "0.0525",
      "settled": true
    },
    "finished_at": "2026-08-05T02:11:20+00:00"
  }
}
```

生成结果地址位于 `data.result.url`。建议业务系统在成功后保存任务 ID、结果 URL 和消耗积分。

### 失败响应

任务执行失败时，查询接口本身仍返回 HTTP `200`，任务数据中的 `status` 为 `failed`：

```json
{
  "object": "image.task",
  "data": {
    "id": "cd9db50e-a246-4945-ad62-c6826c575c1d",
    "status": "failed",
    "stage": "failed",
    "progress": 100,
    "billing": {
      "currency": "CNY",
      "display_unit": "points",
      "reserved_amount": "0.0525",
      "amount": "0.0000",
      "settled": true
    },
    "error": {
      "code": "UPSTREAM_ERROR",
      "message": "上游图片生成失败"
    }
  }
}
```

## 十一、幂等与安全重试

创建任务时强烈建议携带：

```http
Idempotency-Key: 你的业务订单号或请求唯一号
```

规则如下：

- 长度不能超过 120 个字符。
- 同一客户、同一 `Idempotency-Key` 重试时，会返回第一次创建的任务或批次。
- 首次创建通常返回 HTTP `202`；命中已有任务时返回 HTTP `200`。
- 命中幂等任务不会重复排队、重复预占或重复扣除积分。
- 不同业务订单必须使用不同的幂等键。

客户端遇到网络超时、连接中断或未收到响应时，应使用原来的幂等键重试，不要生成新的键。

## 十二、积分规则

- 创建任务时预占积分，积分不足返回参数错误且不创建任务。
- 成功后预占转为实际消耗，积分见 `billing.amount`。
- 失败后该任务预占积分自动退回，`billing.amount` 为 `0.0000`。
- 批量任务逐张结算、逐张退回积分。
- 前端和业务结算统一使用积分，兑换比例为 1 元 = 1 积分；API 数值使用四位小数的字符串表示。
- 为兼容已经接入的客户端，`billing.currency` 暂时保留为 `CNY`；请以新增字段 `billing.display_unit: "points"` 判断展示单位。数值与积分 1:1，不需要换算。

## 十三、错误格式与状态码

接口级错误统一返回：

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "具体错误说明"
  }
}
```

| HTTP 状态码 | 常见错误码 | 说明 |
| ---: | --- | --- |
| `400` | `INVALID_REQUEST` | 字段、比例、模型、数量、积分或上传内容不符合要求 |
| `401` | `INVALID_API_KEY` | API Key 缺失、无效或已停用 |
| `404` | `NOT_FOUND` | 任务不存在，或任务不属于当前客户 |
| `409` | `CONFLICT` | 唯一资源冲突 |
| `429` | `RATE_LIMITED` | 调用过于频繁，请稍后重试 |
| `502` | `IMAGE_GENERATION_FAILED` 或上游错误码 | 同步生成失败，该任务积分已退回 |
| `503` | `MODEL_TEMPORARILY_UNAVAILABLE` | 真实生成连续失败或上游持续拥堵；任务未创建、积分未预占 |
| `504` | `SYNC_WAIT_TIMEOUT` | 同步等待到达上限；任务仍在后台继续，可通过 `task_id` 查询 |
| `500` | `INTERNAL_ERROR` | 平台内部异常 |

遇到 `429` 或普通临时 `5xx` 时，请采用指数退避重试；创建任务重试时必须复用原 `Idempotency-Key`。遇到 `MODEL_TEMPORARILY_UNAVAILABLE` 时不要立即循环重试，建议至少等待 10 分钟；该响应不会创建任务或预占积分。

## 十四、Python 示例

### 同步调用

```python
import uuid
import requests

BASE_URL = "https://image.own-jarvis.com"
API_KEY = "itx_你的客户密钥"

response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"my-sync-order-{uuid.uuid4()}",
    },
    json={
        "model": "gpt-image-2.5",
        "prompt": "一只坐在窗边的橘猫，电影感自然光",
        "aspect_ratio": "3:4",
        "upload_ids": [],
        "image_urls": [],
        "count": 1,
    },
    timeout=900,
)
response.raise_for_status()
print(response.json()["data"][0]["url"])
```

### 异步调用

```python
import time
import uuid
import requests

BASE_URL = "https://image.own-jarvis.com"
API_KEY = "itx_你的客户密钥"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": f"my-order-{uuid.uuid4()}",
}

response = requests.post(
    f"{BASE_URL}/v1/images/tasks",
    headers=headers,
    json={
        "model": "gpt-image-2",
        "prompt": "一只坐在窗边的橘猫，电影感自然光",
        "aspect_ratio": "3:4",
        "upload_ids": [],
        "image_urls": [],
        "count": 1,
    },
    timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["id"]

while True:
    result = requests.get(
        f"{BASE_URL}/v1/images/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()["data"]
    if task["status"] == "succeeded":
        print(task["result"]["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", {}).get("message", "生成失败"))
    time.sleep(3)
```

批量任务的创建响应是 `image.batch`。需要遍历 `response.json()["data"]["tasks"]`，分别保存和查询每个任务 ID。

## 十五、接入建议

- API Key 只保存在服务端，通过环境变量或密钥管理服务加载。
- 业务数据库保存 `Idempotency-Key`、ImageTo 任务 ID、状态、结果 URL 和消耗积分。
- 单张且调用链可以保持 900 秒连接时，可使用同步接口简化接入；批量、浏览器直连或需要可靠断线恢复时，优先使用异步任务接口。
- 对批量任务设置整体进度，同时保留每张图片的独立状态。
- 用户主动取消自己页面的等待，不代表平台任务已取消；后续仍可通过任务 ID恢复查询。
- 需要协助排查时，请提供平台任务 ID，不要在聊天或工单中发送完整 API Key。