본문으로 건너뛰기
Cheapest Imagen
가이드

동기 요청과 비동기 요청

이미지 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"])) < 300
import { 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로 응답합니다.

이 페이지의 내용