동기 요청과 비동기 요청
이미지 API를 호출하는 두 가지 방법입니다. 한 번의 요청으로 이미지를 기다리거나, async true를 보내 작업 ID를 바로 받고 폴링 한 번 또는 웹훅으로 작업을 조회합니다.
이미지를 만드는 방법은 두 가지입니다. 두 방법은 같은 파라미터를 사용하고, 요금과 제한도 같으며, 요청마다 고를 수 있습니다.
| 동기(기본값) | 비동기 | |
|---|---|---|
| 방법 | 요청을 보내고 기다립니다 | async: true를 추가하고 작업 ID를 바로 받습니다 |
| 응답이 도착하는 시점 | 20초에서 몇 분 뒤, 같은 응답 안에서 | 나중에: 직접 폴링하거나 웹훅이 호출됩니다 |
| 연결 유지 시간 | 이미지가 준비될 때까지 | 1초 미만 |
| 최대 실행 시간 | 7분 | 10분 |
| 반환 값 | 이미지 데이터(b64_json) 또는 링크(url) | 링크(url) |
| 호환 도구 | OpenAI SDK와 OpenAI Images API용으로 만든 모든 도구 | 모든 HTTP 클라이언트 |
| 적합한 용도 | 스크립트, 백엔드, 이미지를 한 장씩 만들 때 | 웹 페이지, 한꺼번에 많은 이미지, 느린 모델, 실행 시간 제한이 짧은 서버리스 함수 |
세 가지 호출
| 호출 | 동작 |
|---|---|
async: true를 붙인 POST /v1/images/generations 또는 /v1/images/edits | 작업을 시작합니다. 작업 ID와 함께 202로 응답합니다 |
GET /v1/images/tasks?ids=a,b,c | 요청 한 번으로 최대 100개 작업의 상태를 조회합니다 |
GET /v1/images/tasks/{id} | 작업 하나의 상태를 조회합니다 |
1. 작업 시작하기
POST /v1/images/generations의 본문에 async: true를 추가하거나, POST /v1/images/edits에서는 폼 필드로 추가합니다.
curl https://api.cheapestimagen.com/v1/images/generations \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true}'응답은 202 Accepted이며, 1초가 채 걸리지 않습니다.
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}id를 보관해 두세요. 알아 둘 점이 세 가지 있습니다.
- 링크만 제공됩니다. 작업의 이미지는 링크로 반환되므로
response_format을 생략하거나url로 설정하세요.b64_json은400으로 거부됩니다. - 잘못된 요청은 나중이 아니라 이 단계에서 실패합니다. 잘못된 파라미터(
400), 크레딧 부족(402), 요청 과다(429)는 동기 요청과 마찬가지로 바로 응답합니다. 이 경우 작업은 만들어지지 않습니다. - 본문 필드를 쓸 수 없나요?
Prefer: respond-async헤더가async: true와 같은 역할을 합니다.
2. 작업 조회하기
요청 한 번으로 여러 작업 조회
작업이 둘 이상이면 한꺼번에 조회하세요. 작업 10개를 시작한 페이지는 폴링 요청을 10번이 아니라 한 번만 보냅니다.
curl "https://api.cheapestimagen.com/v1/images/tasks?ids=req_33ac10d3e9a8e6f120f4c0d3,req_26e50328772b7d62f59d355a" \
-H "Authorization: Bearer YOUR_KEY"{
"object": "list",
"data": [
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "succeeded",
"created": 1795062073,
"finished": 1795062098,
"model": "gpt-image-2.6",
"result": {
"created": 1795062098,
"data": [{ "url": "https://img.cheapestimagen.com/g/req_33ac10d3e9a8e6f120f4c0d3/0.png" }]
}
},
{
"id": "req_26e50328772b7d62f59d355a",
"object": "image.task",
"status": "in_progress",
"created": 1795062074,
"finished": null,
"model": "gpt-image-2.6"
}
],
"not_found": []
}ids에는 쉼표로 구분한 작업 ID를 최대 100개까지 넣을 수 있습니다.data에는 요청하신 순서대로 작업이 담깁니다.- 내 계정의 작업이 아니거나 이미지가 더 이상 보관되지 않는 ID는
not_found에 나열됩니다. 이 때문에 요청이 실패하지는 않습니다.
작업 하나 조회
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"응답은 작업 객체 하나입니다. 알 수 없는 ID는 404로 응답합니다.
작업 상태의 의미
status | 의미 | 추가 필드 |
|---|---|---|
in_progress | 이미지를 만드는 중입니다 | 없음 |
succeeded | 완료되었습니다 | result: 동기 호출이 반환했을 내용과 동일한 { created, data: [{ url }] } |
failed | 실패했습니다 | error: 동기 호출이 반환했을 오류와 동일한 내용 |
실패한 작업은 다음과 같습니다.
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "failed",
"created": 1795062073,
"finished": 1795062110,
"model": "gpt-image-2.6",
"error": { "message": "The image provider failed. You were not charged.", "type": "api_error", "param": null, "code": "upstream_error" }
}실패한 작업은 과금되지 않습니다. 예외는 동기 요청과 같습니다. Nano Banana 안정 채널의 거부입니다.
폴링 주기
2~5초마다 확인하면 충분합니다. 작업 조회는 무료이며 이미지 요청이 아니므로 진행 중인 요청 수에 포함되지 않습니다. 작업은 이미지가 보관되는 동안인 72시간 동안 조회할 수 있습니다.
예시: 이미지 10장을 시작하는 웹 페이지
이미지마다 요청 하나로 작업을 시작한 뒤, 모든 작업을 3초마다 요청 한 번으로 조회합니다.
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// 작업 10개를 시작합니다.
const prompts = Array.from({ length: 10 }, (_, i) => `a red fox in the snow, variation ${i + 1}`);
const started = await Promise.all(prompts.map((prompt) =>
fetch(`${API}/images/generations`, {
method: "POST", headers,
body: JSON.stringify({ model: "gpt-image-2.6", prompt, async: true }),
}).then((r) => r.json())
));
// 진행 중인 작업이 없을 때까지 요청 한 번으로 모두 폴링합니다.
let waiting = started.map((t) => t.id);
const done = {};
while (waiting.length) {
await new Promise((r) => setTimeout(r, 3000));
const { data } = await fetch(`${API}/images/tasks?ids=${waiting.join(",")}`, { headers }).then((r) => r.json());
for (const task of data) if (task.status !== "in_progress") done[task.id] = task;
waiting = waiting.filter((id) => !done[id]);
}
for (const task of Object.values(done)) {
console.log(task.status === "succeeded" ? task.result.data[0].url : task.error.message);
}API 키를 공개 웹 페이지에 넣지 마세요. 자신의 서버에서 API를 호출하고, 페이지는 그 서버와 통신하도록 하세요.
예시: Python
import time, requests
API = "https://api.cheapestimagen.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}
ids = [
requests.post(f"{API}/images/generations", headers=HEADERS, json={
"model": "gpt-image-2.6", "prompt": f"a red fox in the snow, variation {i}", "async": True,
}).json()["id"]
for i in range(10)
]
done = {}
while len(done) < len(ids):
time.sleep(3)
waiting = [i for i in ids if i not in done]
tasks = requests.get(f"{API}/images/tasks", headers=HEADERS, params={"ids": ",".join(waiting)}).json()["data"]
done.update({t["id"]: t for t in tasks if t["status"] != "in_progress"})
for t in done.values():
print(t["result"]["data"][0]["url"] if t["status"] == "succeeded" else t["error"]["message"])OpenAI SDK에서는 extra_body={"async": True}로 필드를 전달하고, 작업 조회는 일반 HTTP 요청으로 하세요.
폴링 대신 웹훅
webhook_url을 추가하면 완료된 작업을 해당 주소로 POST합니다.
{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }- 주소는 공개 호스트 이름의
https://여야 합니다. - 본문은 작업 객체이며,
GET /v1/images/tasks/{id}와 같은 JSON입니다. - 10초 안에 아무
2xx로나 응답하세요. 그렇지 않으면 3초 뒤와 15초 뒤에 두 번 더 시도한 다음 중단합니다. - 호출에 서명을 받으려면 요청과 함께 직접 정한 비밀 값을
webhook_secret(16~128자)으로 보내세요. 보내지 않으면 호출에 서명이 없습니다. 이 경우 알림으로만 취급하고, 호출에서id를 꺼내 키로 작업을 조회해 내용을 확인한 뒤에 신뢰하세요. - 웹훅이 도착했는지와 관계없이 작업은 계속 조회할 수 있으므로, 놓친 호출이 있어도 잃는 것은 없습니다.
서명 확인
webhook_secret을 보냈다면 호출에 x-webhook-signature: t=1763560000,v1=5f2b… 헤더가 포함됩니다. t는 호출 시각(Unix 초)이고, v1은 비밀 값으로 <t>.<body> 텍스트에 대해 계산한 HMAC-SHA256의 16진수 값입니다. 받은 원본 요청 본문으로 같은 값을 계산해 비교하고, t가 몇 분 이상 지난 호출은 거부하세요.
import hashlib, hmac, time
def is_ours(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300import { createHmac, timingSafeEqual } from 'node:crypto';
function isOurs(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}JSON으로 파싱하기 전에, 도착한 그대로의 본문을 사용하세요. 비밀 값은 이 요청에서만 사용되며 계정에 저장되지 않습니다.
제한
비동기 요청도 동기 요청과 똑같이 계산됩니다. 계정당 분당 300건, 진행 중 50건입니다. 50건이 실행 중일 때 보낸 요청은 429로 거부되므로, 하나가 끝나기를 기다리세요. 작업 조회는 집계되지 않습니다.
Idempotency-Key도 같은 방식으로 동작합니다. 해당 키의 요청이 실행 중이거나 성공한 뒤에 다시 보내면 409로 응답합니다.