本页目录
图片生成开发者预览
GPT Image 2 API
通过一套稳定的异步 API 调用提示词或参考图生成图片。imya 负责模型路由、任务状态、积分扣费和生成资产。
REST API · v1 · 异步任务
开发者预览：公开 API 契约已可评审。正式 /v1 接口和积分路径完成端到端验证前，不开放生产流量。
完成第一次调用
API 采用异步任务：先创建任务并保存 task ID，再查询任务，直到结果生成完成。
- 1
创建 API Key
在 imya 账户设置中生成一枚密钥。
- 2
创建任务
提交模型 ID、提示词和输出参数。
- 3
获取结果
轮询任务，或在完成时接收 callback。
身份验证
每次请求都要把 imya API Key 作为 Bearer Token 发送。密钥只能保存在服务端，不能暴露在浏览器代码中。
HTTP
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json创建图片生成任务
创建异步 GPT Image 2 任务，并预留预计所需积分。
POST
/v1/images/generations请求
curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A luxury perfume product photo on warm marble, soft studio light",
"size": "1:1",
"quality": "medium",
"n": 1
}'查询任务
返回最新任务状态、最终积分消耗、生成资产或结构化错误。
GET
/v1/tasks/{task_id}请求
curl https://imya.ai/v1/tasks/task_01jz_example \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 使用 gpt-image-2。 |
| prompt | string | 是 | 图片生成提示词。 |
| size | string | 否 | 1:1、3:2、2:3、4:3、3:4、16:9 或 9:16。 |
| quality | string | 否 | medium 或 high。 |
| n | number | 否 | 生成图片数量，默认 1。 |
| image_urls | string[] | 否 | 图生图参考图片。 |
| callback_url | string | 否 | 可选 HTTPS Webhook 地址。 |
返回结构
已接收返回
{
"id": "task_01jz_example",
"status": "pending",
"model": "gpt-image-2",
"credits_reserved": 13
}完成返回
{
"id": "task_01jz_example",
"status": "succeeded",
"model": "gpt-image-2",
"credits_used": 13,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png",
"width": 1024,
"height": 1024
}
]
}积分计费
积分从 API Key 所属用户账户扣除。创建任务时返回预留估算，任务完成后返回最终实际消耗。最终扣费由模型、生成数量、画质和会员折扣共同决定。
任务状态
pending任务已接收，正在等待处理。
processing模型正在生成请求的内容。
succeeded生成完成，data 中包含最终资产。
failed生成失败，请读取结构化 error 对象。
错误码
401API Key 缺失或无效。
402账户积分不足。
422模型、提示词、尺寸或画质参数无效。
429API Key 达到速率或并发上限。
500上游生成服务或 imya 服务返回错误。
接入前想先测试模型？
打开 GPT Image 2 在线生成器，无需写代码即可比较提示词和输出设置。
在线试用 GPT Image 2