教程
GPT Image 2.5 Sunburst 文生图 API：可用的 curl 与 Python 指南
如果你想通过 hiapi API 使用 gpt-image-2.5-sunburst/text-to-image 生成图像，本指南将带你完成一次完整且可用的请求，分别使用 curl 和 Python——从创建任务到下载最终的图像 URL。此处展示的每个请求/响应都是在发布前针对线上 API 实际运行过的。
前提条件
- 拥有 hiapi 账户和 API key（
sk-...）。可在 hiapi 控制台获取。 curl，或者如果你要跟着 Python 示例操作，需要 Python 3.8+。- 至少一张输出图像的预算。
gpt-image-2.5-sunburst/text-to-image按输出分辨率计费——在生产环境运行前请查看当前定价，因为费率可能会变动。
所有请求都使用标准请求头：
Authorization: Bearer sk-your-api-key-here
Content-Type: application/json
最小可用示例
hiapi 的图像模型都运行在同一个异步任务 API 上：你通过 POST 创建一个任务，然后轮询（或获取 webhook 回调）直到它达到终态，再从 output[0].url 中读取图像 URL。
1. 创建任务（curl）
curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer sk-your-api-key-here" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-sunburst/text-to-image",
"input": {
"prompt": "A minimalist product shot of a ceramic coffee dripper on a marble counter, soft morning light, 35mm lens look",
"resolution": "2K",
"aspect_ratio": "4:3",
"background": "auto"
}
}'
调用成功只会返回一个任务 ID——生成是异步进行的：
{"code":200,"data":{"taskId":"tk-hiapi-01ABCDEF..."},"message":"success"}
2. 轮询结果
curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01ABCDEF..." \
-H "Authorization: Bearer sk-your-api-key-here"
每隔几秒持续轮询，直到 data.status 成为终态值。成功时，响应如下所示（taskId/URL 为便于阅读已缩短）：
{
"code": 200,
"data": {
"taskId": "tk-hiapi-01ABCDEF...",
"model": "gpt-image-2.5-sunburst/text-to-image",
"status": "success",
"storage": "temp",
"created": 1789144334,
"completed": 1789144407,
"output": [
{
"type": "image",
"url": "https://temp.hiapi.ai/.../output-0.png",
"artifactId": "146251",
"expireAt": 1789749206
}
]
},
"message": "success"
}
从 data.output[0].url 获取图像。该 URL 会过期（参见 expireAt，一个 Unix 时间戳）——任务成功后请立即下载字节并自行存储，不要把它当作永久链接。
3. Python 端到端示例
import time
import requests
API_KEY = "sk-your-api-key-here"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
def create_task(prompt: str, resolution: str = "1K", aspect_ratio: str = "1:1") -> str:
payload = {
"model": "gpt-image-2.5-sunburst/text-to-image",
"input": {
"prompt": prompt,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
},
}
resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
return resp.json()["data"]["taskId"]
def wait_for_task(task_id: str, timeout_s: int = 300, poll_interval: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()["data"]
if task["status"] == "success":
return task
if task["status"] == "fail":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")
if __name__ == "__main__":
task_id = create_task("A minimalist product shot of a ceramic coffee dripper on a marble counter")
task = wait_for_task(task_id)
image_url = task["output"][0]["url"]
print(f"Done: {image_url}")
img_bytes = requests.get(image_url, timeout=60).content
with open("output.png", "wb") as f:
f.write(img_bytes)
input 实际接受哪些字段
gpt-image-2.5-sunburst/text-to-image 的 schema 小而严格。只接受以下字段——其他任何字段（quality、size、n、output_format、style、seed）都会以 400 被拒绝：
| 字段 | 必填 | 取值 |
|---|---|---|
prompt |
是 | 任意字符串 |
resolution |
否（默认为 1K） |
1K、2K、4K |
aspect_ratio |
否 | auto、1:1、3:2、2:3、4:3、3:4、16:9、9:16、21:9、27:16、16:27、9:8、8:9 |
background |
否 | transparent、opaque、auto |
请注意，这与裸 gpt-image-2.5-sunburst 模型的 schema 不同：后者接受 quality 档位（low/medium/high/xhigh/max/auto），并支持通过 image_urls 进行图生图编辑。两者的定价也不同——在依赖具体数字之前，请对照 /en/pricing 核实，因为费率可能会变动。
生产环境模式
使用 Webhook 回调代替轮询
对于快速脚本之外的任何场景，跳过轮询，让 hiapi 在任务完成时回调你。在同一个 POST /v1/tasks 请求中添加顶层 callback 对象：
{
"model": "gpt-image-2.5-sunburst/text-to-image",
"input": { "prompt": "..." },
"callback": {
"url": "https://your-app.example.com/webhooks/hiapi",
"when": "final"
}
}
when: "final" 是目前唯一支持的值——当任务达到终态（success 或 fail）时，你的端点会被调用一次，负载结构与轮询得到的结果相同。
轮询 vs. 回调：轮询在脚本或 notebook 中更易正确实现，且不需要公网端点，但会浪费请求并增加延迟（平均为你的轮询间隔），你才能得知完成。对于服务端集成或任何高并发场景，回调更合适——你完全避开轮询循环，任务一落地就会收到通知。
重试时的幂等性
任务 API 接受顶层 idempotency_key 字符串，与 model/input/callback 并列。如果你的客户端可能在超时后重试 POST（你发送了请求，但从未收到响应），请附加一个稳定的 key，这样你就有了一个清晰的信号来核对，而不是猜测原始请求是否真的落地。
处理错误
无效或过期的 API key 会返回 HTTP 401 和结构化错误体：
{
"error": {
"code": "permission_denied",
"message": "This API key is invalid. Check that it is correct or use another API key and try again.",
"request_id": "2026...",
"type": "hiapi_error"
}
}
错误的 input 值（错误的枚举成员、缺少 prompt、不支持的字段）会在创建任务之前返回 HTTP 400——因此不会向你收费：
{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}
请显式检查这两种情况：对瞬时网络/5xx 错误进行重试，但将 400 视为修复请求体的信号，而不是盲目重试的对象。
相关资源
- gpt-image-2.5-sunburst 模型页面——裸模型和
/text-to-image路由的完整参数参考与实时定价。 - hiapi 定价——本模型及其他所有模型的当前按分辨率费率。
- GPT Image 2.5 Sunburst 提示词配方——在你开始写脚本前，如果你想找灵感，这里有可参考的提示词示例。
常见问题
我需要指定 resolution 吗？ 不需要——如果省略，默认为 1K。如果你需要 2K 或 4K 输出，请显式设置，因为价格随分辨率提升。
我能像其他 GPT Image 模型的文档那样传入 quality 吗？ 在此路由上不能。gpt-image-2.5-sunburst/text-to-image 完全拒绝 quality——该参数只存在于裸 gpt-image-2.5-sunburst 模型 ID 上，后者有不同 schema 和定价。
为什么我的请求返回任务 ID 而不是直接返回图像？ hiapi 上的每个图像模型都通过同一个异步任务 API 运行（POST /v1/tasks → 轮询或回调 → output[0].url），无论底层模型实际有多快。围绕该模式构建一次集成，之后你换入的每个模型都会以相同方式工作。
如果我没有及时下载输出 URL 会怎样？ 它会过期——任务响应中的 expireAt 字段是临时 URL 停止工作的 Unix 时间戳。一旦 status 为 success，请立即自行下载并存储字节。
我能用此模型进行图生图编辑吗？ 在 /text-to-image 路由上不能。对于图像编辑，请使用裸 gpt-image-2.5-sunburst 模型 ID，并传入 image_urls 输入字段——查看其模型页面了解确切 schema。
准备好自己尝试了吗？从 hiapi 控制台获取 API key，并替换上面 Python 示例中的 prompt 即可。
