# gpt-image-2 — Scenepond API

模型 ID: `gpt-image-2`

模型开发者: OpenAI

原始页面: https://open.scenepond.ai/zh/models/gpt-image-2#api

核对日期: 2026-10-11

API 地址: `https://open.scenepond.ai/v1`

每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。

## Scenepond 异步任务

`POST /v1/tasks`

### 最小调用

#### cURL

```bash
curl --fail-with-body -X POST "https://open.scenepond.ai/v1/tasks" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gpt-image-2",
  "parameters": {
    "prompt": "A cat walking on a quiet beach",
    "count": 1,
    "size": "1024x1024",
    "quality": "low"
  }
}
JSON
```

#### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

payload = json.loads("{\n  \"model\": \"gpt-image-2\",\n  \"parameters\": {\n    \"prompt\": \"A cat walking on a quiet beach\",\n    \"count\": 1,\n    \"size\": \"1024x1024\",\n    \"quality\": \"low\"\n  }\n}")

request = Request(
    "https://open.scenepond.ai/v1/tasks",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

#### JavaScript

```javascript
const response = await fetch("https://open.scenepond.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "model": "gpt-image-2",
  "parameters": {
    "prompt": "A cat walking on a quiet beach",
    "count": 1,
    "size": "1024x1024",
    "quality": "low"
  }
})
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 请求参数

- `model` — **必填**; `string`. 使用此处显示的完整公开模型 ID。
  - 约束: `const = "gpt-image-2"`

- `parameters` — **必填**; `object`. 此模型的生成参数。

### parameters 中的字段

仅在提供 parameters 时适用；子字段必填不代表可选的父字段也必填。

- `parameters.prompt` — **必填**; `string`. 描述主体、场景和期望生成的内容。
  - 约束: `length = 1..32000`

- `parameters.count` — **可选**; `integer`. 本次任务请求生成的图片数量。
  - 约束: `minimum = 1`; `maximum = 10`

- `parameters.size` — **可选**; `string`. 输出图片尺寸，使用 auto 或支持的宽×高。
  - 约束: `边长必须是 16 的倍数`; `maximum edge = 3840`; `pixels = 655360..8294400`; `maximum aspect ratio = 3:1`

- `parameters.quality` — **可选**; `string`. 期望的图片质量等级。
  - 约束: `enum = auto, low, medium, high`

- `parameters.image_urls` — **可选**; `string[]`. 可选参考图片，提供后执行图片编辑。
  - 约束: `items = 1..16`

- `parameters.mask_url` — **可选**; `string`. 图片编辑使用的可选遮罩 URL。

- `parameters.background` — **可选**; `string`. 生成图片的背景类型。
  - 约束: `enum = auto, opaque, transparent`

- `parameters.output_format` — **可选**; `string`. 生成图片的编码格式。
  - 约束: `enum = png, jpeg, webp`

- `parameters.output_compression` — **可选**; `integer`. 输出压缩百分比。
  - 约束: `minimum = 0`; `maximum = 100`

- `parameters.moderation` — **可选**; `string`. 图片审核级别。
  - 约束: `enum = auto, low`


### 响应示例

响应示例仅展示结构；ID、URL 和数值为占位内容。

#### 提交响应

```json
{
  "task_id": "task_EXAMPLE",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1700000000,
  "finished_at": 0,
  "error": null,
  "links": {
    "self": "/v1/tasks/task_EXAMPLE",
    "artifacts": "/v1/tasks/task_EXAMPLE/artifacts"
  }
}
```

#### 已完成任务的状态

```json
{
  "task_id": "task_EXAMPLE",
  "model": "gpt-image-2",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1700000000,
  "finished_at": 1700000060,
  "error": null,
  "links": {
    "self": "/v1/tasks/task_EXAMPLE",
    "artifacts": "/v1/tasks/task_EXAMPLE/artifacts"
  }
}
```

#### 生成文件列表

```json
{
  "task_id": "task_EXAMPLE",
  "artifacts": [
    {
      "key": "image_0",
      "type": "image",
      "content_url": "https://open.scenepond.ai/v1/tasks/task_EXAMPLE/artifacts/image_0/content"
    }
  ]
}
```

### 后续请求

#### 2. 查询任务状态

每隔几秒查询一次，直到 succeeded 或 failed。

##### cURL

```bash
curl --fail-with-body -X GET "https://open.scenepond.ai/v1/tasks/$SCENEPOND_TASK_ID" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://open.scenepond.ai/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://open.scenepond.ai/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

#### 3. 获取生成结果

任务 succeeded 后列出结果，并使用 content_url 下载。请勿公开签名 URL。

##### cURL

```bash
curl --fail-with-body -X GET "https://open.scenepond.ai/v1/tasks/$SCENEPOND_TASK_ID/artifacts" \
  -H "Authorization: Bearer $SCENEPOND_API_KEY"
```

##### Python

```python
import os
import json
from urllib.parse import quote
from urllib.request import Request, urlopen

request = Request(
    "https://open.scenepond.ai/v1/tasks/" + quote(os.environ["SCENEPOND_TASK_ID"], safe="") + "/artifacts",
    headers={
        "Authorization": "Bearer " + os.environ["SCENEPOND_API_KEY"],
        "Content-Type": "application/json",
    },
    method="GET",
)
with urlopen(request) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
```

##### JavaScript

```javascript
if (!process.env.SCENEPOND_TASK_ID) throw new Error("Set SCENEPOND_TASK_ID first");
const response = await fetch("https://open.scenepond.ai/v1/tasks/" + encodeURIComponent(process.env.SCENEPOND_TASK_ID) + "/artifacts", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.SCENEPOND_API_KEY}`,
    "Content-Type": "application/json"
  }
});
if (!response.ok) throw new Error(`API error: ${response.status} ${await response.text()}`);
const result = await response.json();
console.log(result);
```

### 调用注意事项

- 图片和视频使用同一套任务接口。选择模型后，系统自动选择渠道。
- 每次请求使用 Authorization: Bearer 和 Scenepond API Key 认证；密钥保存在服务器。
- 提交一次并保存 task_id，轮询至 succeeded 或 failed，再通过结果接口下载。
- 上游接受请求后返回任务信息；同步上游可能在返回任务 ID 前完成生成。
- POST 超时后请勿自动重提，任务可能已创建并产生费用。
- 参数和限制因模型而异，只接受此模型列出的字段。