작업 완료 콜백(Webhook)

​

빠른 시작

curl -X POST https://여러분의접속도메인/v1/images/generations \
  -H "Authorization: Bearer 여러분의APIKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red apple on a table",
    "size": "1024x1024",
    "webhook": "https://your-server.com",
    "language": "ko"
  }'

​

오류 메시지 언어 지정

• 대소문자를 구분하지 않으며 앞뒤 공백은 자동으로 제거됩니다. 예를 들어 "KO"와 " ko "는 모두 ko로 처리됩니다.
• 표에 있는 두 글자 언어 코드를 사용하세요. zh-CN, en-US, pt-BR 등의 지역 태그는 인식되지 않습니다.
• 지원되지 않는 값을 전달해도 작업 제출은 실패하지 않으며, 콜백에는 원본 오류 메시지가 포함됩니다.
• 원본 메시지가 이미 대상 언어이면 다시 번역하지 않고 그대로 반환합니다.
• 번역에 실패해도 콜백을 지연하거나 누락하지 않고 원본 메시지를 반환합니다.

​

URL 규칙

​

무엇을 받게 되나요

{
  "id": "task_01KV7FXR8BEYS1BWHJCT3JMCJ5",
  "status": "completed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589058,
  "actual_time": 29,
  "cost": 0.006,
  "credits_cost": 0.06,
  "result": {
    "images": [{ "url": ["https://.../result.png"], "expires_at": 1781675458 }]
  }
}

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 100,
  "created": 1781589029,
  "completed": 1781589050,
  "error": {
    "message": "입력 이미지에 액세스할 수 없습니다. URL이 공개적으로 액세스 가능한지 확인하세요",
    "type": "task_failed",
    "param": "",
    "code": "task_failed"
  }
}

​

재시도와 중복 제거(중요)

• 재시도: 서버가 약 10초 이내에 2xx 를 반환하지 않거나 5xx 를 반환하면, 자동으로 최대 3회 재시도하며 간격은 약 10초, 30초, 60초 입니다. 3회 모두 실패하면 포기합니다(약 2분 이내 종료).
• 재시도하지 않는 경우: 엔드포인트가 4xx 를 반환하면(URL / 요청에 문제가 있다고 간주) 재시도 없이 즉시 포기합니다.
• 중복 제거: 일반적으로 한 작업은 한 번만 푸시됩니다. 다만 극단적인 경우(예: 전송 후 확인 전에 당사 측에서 재시작 발생) 중복 푸시를 받을 수 있습니다. 중복 처리를 방지하기 위해 반드시 id(task_id) 기준으로 멱등하게 중복 제거 하세요.

​

콜백 URL 요구 사항

​

자주 묻는 질문

​

최소 수신 측 예제

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_POST(self):
        n = int(self.headers.get("Content-Length") or 0)
        body = self.rfile.read(n)
        data = json.loads(body)
        print("작업 콜백 수신:", data["id"], data["status"])
        # TODO: id 로 중복 제거하고 서명을 검증한 뒤 처리
        self.send_response(200); self.end_headers()
        self.wfile.write(b'{"ok":true}')

HTTPServer(("0.0.0.0", 443), H).serve_forever()