이 페이지
GPT Image 2 API
예측 가능한 비동기 API로 프롬프트와 선택적 참조 이미지에서 GPT Image 2 이미지 한 장을 생성합니다. Imya가 작업 상태, 현재 플랜 요금과 결과 자산을 관리합니다.
REST API · v1 · 비동기 작업
첫 요청 보내기
먼저 작업을 만들고 반환된 task ID를 저장한 다음 결과가 준비될 때까지 작업을 조회합니다.
- 1
API Key 생성
Imya 계정 설정에서 키를 발급합니다.
- 2
작업 생성
모델 ID, 프롬프트와 출력 옵션을 보냅니다.
- 3
결과 조회
성공하거나 실패할 때까지 작업을 조회합니다.
인증과 멱등성
Imya API Key를 Bearer 토큰으로 보냅니다. 모든 생성 POST에는 고유한 Idempotency-Key가 필요하며 안전한 재시도는 작업이나 과금을 중복 생성하지 않습니다.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY이미지 생성 작업 만들기
비동기 GPT Image 2 작업을 만들고 credits_reserved로 반환되는 정확한 크레딧을 원자적으로 차감합니다.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gpt-image-order-001" \
-d '{
"model": "gpt-image-2",
"prompt": "A luxury perfume product photo on warm marble, soft studio light",
"aspect_ratio": "1:1",
"resolution": "1K",
"n": 1
}'작업 조회
최신 상태, 최종 크레딧, 생성 자산 또는 구조화 오류를 반환합니다. 5초 이상 간격으로 조회하세요. 더 빠른 요청은 속도 제한에 포함되지만 업스트림 상태를 갱신하지 않습니다.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"요청 파라미터
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | gpt-image-2를 사용합니다. |
| prompt | string | 예 | 이미지 생성을 위한 텍스트 프롬프트입니다. 1~20,000자입니다. |
| aspect_ratio | string | 아니요 | auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9 또는 9:21. |
| resolution | string | 아니요 | 1K, 2K 또는 4K. 일부 비율은 1K만 지원합니다. |
| n | number | 아니요 | 반드시 1이며 이미지 한 장만 생성합니다. |
| image_urls | string[] | 아니요 | 이미지 변환용 공개 HTTPS 참조 이미지 1~16장. |
응답
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 13
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:42.000Z",
"credits_reserved": 13,
"credits_used": 13,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}크레딧 과금
기본 비용은 1K 10크레딧, 2K 15크레딧, 4K 24크레딧입니다. 서버가 API Key 소유자의 플랜 계수를 적용하고 실제 비용을 credits_reserved로 반환합니다. 예시는 일반 계정의 1K 생성 13크레딧입니다. 항상 응답 값을 사용하며 n은 1로 고정됩니다.
작업 상태
pending작업이 접수되어 시작을 기다립니다.
processing모델이 요청한 출력을 생성 중입니다.
succeeded생성이 끝났고 data에 자산이 포함됩니다.
failed생성에 실패했습니다. 구조화된 error 객체를 확인하세요.
오류
400Idempotency-Key가 없거나 JSON 형식이 잘못되었습니다.
401API Key가 없거나 유효하지 않습니다.
402계정 크레딧이 부족합니다.
403API 계정이 비활성화되었습니다.
404작업을 찾을 수 없거나 이 계정 소유가 아닙니다.
409같은 멱등 키를 다른 요청 본문에 재사용했습니다.
413요청 본문이 64 KiB를 초과합니다.
415Content-Type은 application/json이어야 합니다.
422모델, 프롬프트, 비율, 해상도, n 또는 참조 이미지가 유효하지 않습니다.
429API Key의 속도 또는 동시 실행 한도에 도달했습니다.
5xx요청을 완료하거나 제출하지 못했습니다.
Imya 공개 API 공통 계약
다음 규칙은 모든 공개 이미지·동영상 생성 엔드포인트에 적용됩니다. 모델별 필드와 요금은 위 파라미터 표를 따릅니다.
과금과 안전한 재시도
새 작업이 접수될 때 credits_reserved의 정확한 크레딧을 원자적으로 차감합니다. 같은 Idempotency-Key와 본문을 재전송하면 중복 과금 없이 원래 작업을 반환합니다.
시간 초과와 환불
30분 안에 종료되지 않은 작업은 실패합니다. 대상 크레딧은 원래 만료일을 유지하며 한 번만 환불됩니다.
속도와 동시 실행 제한
API Key당 60초에 120회 요청, 계정당 이미지 5개 또는 동영상 3개의 동시 작업 한도를 적용합니다. 429의 Retry-After를 따르세요.
조회와 소유권
생성 응답의 id로 GET /v1/tasks/{id}를 5초 이상 간격으로 조회합니다. 생성한 계정만 작업을 읽을 수 있으며 webhook, SDK, batch 제출은 제공하지 않습니다.
오류와 콘텐츠 안전
공개 오류는 업스트림 자격 증명, 내부 URL과 인프라 정보를 제거합니다. 안전하지 않은 프롬프트는 prompt_blocked로 거부될 수 있습니다.
이미지 결과 보관
무료 계정은 7일, 활성 유료 또는 Lifetime 계정은 최대 30일 보관합니다. 삭제 후 status는 failed이고 error.code는 media_deleted입니다.
GPT Image 2 API 프로덕션 연동 가이드
GPT Image 2 연동을 긴 HTTP 요청이 아니라 복구 가능한 비동기 작업 시스템으로 설계하세요. Imya가 반환한 id를 저장하고 재시도를 결정적으로 처리합니다.
모델 계약에서 파라미터 선택
제출 전에 이 페이지의 파라미터 표로 요청을 검증하세요. 최소 지원 설정부터 시작하고 제품에 필요할 때만 품질, 크기, 길이 또는 참조 수를 늘립니다.
참조 순서를 보존하고 사용자가 모든 이미지에 대한 권리를 보유했는지 확인하세요.
복구 가능한 비동기 흐름 설계
이미지 작업을 제출하고 id를 저장한 뒤 백그라운드 워커에서 GET /v1/tasks/{id}를 5초 이상 간격으로 조회합니다. 공개 status는 pending, processing, succeeded, failed이며 30분의 하드 마감에 도달하면 중지합니다. webhook, SDK, batch 제출은 현재 제공하지 않습니다.
- 01UI 업데이트 전에 id, status, credits_reserved와 요청 식별자를 저장합니다.
- 02일시적 오류에는 백오프하고 429의 Retry-After를 준수하며 전송 오류를 새 유료 작업으로 자동 변환하지 않습니다.
- 03계정당 동시에 최대 5개의 이미지 작업과 API Key당 60초에 120회 요청을 허용합니다.
과금과 재시도를 결정적으로 처리
새 작업 접수 시 credits_reserved가 원자적으로 차감됩니다. 의도한 생성마다 Idempotency-Key를 저장하고 같은 본문으로 재사용하면 중복 과금 없이 원래 작업이 반환됩니다.
대상 실패 작업은 원래 만료일을 유지해 한 번만 환불됩니다. 처리 중에는 error.code가 refund_pending이고 완료 후 credits_refunded가 표시됩니다.
자격 증명, 소유권과 미디어 보호
API Key를 서버에 보관하고 id를 인증된 사용자 또는 워크스페이스에 연결하세요. 지원용 요청·작업 ID만 기록하고 프롬프트, 비공개 URL과 자격 증명을 노출하지 마세요.
이미지는 무료 계정 7일, 활성 유료 또는 Lifetime 계정 최대 30일 사용할 수 있습니다. 삭제 후 status는 failed이고 error.code는 media_deleted입니다.
프로덕션 체크리스트
- 제출 전에 모델별 필드를 검증합니다.
- 작업마다 Idempotency-Key와 본문을 저장합니다.
- 상태를 저장하고 5초 이상 간격으로 조회합니다.
- 계정 동시 실행과 Key 속도 제한을 적용합니다.
- 네 status와 media_deleted, refund_pending, credits_refunded를 처리합니다.
- 자격 증명을 서버에 두고 보관 정책을 정의합니다.
자주 묻는 질문
얼마나 자주 조회해야 하나요?
최소 5초를 기다리고 처리 중에는 더 느린 백오프를 사용하세요.
크레딧은 언제 차감되나요?
새 작업 접수 시 정확한 credits_reserved가 원자적으로 차감됩니다.
재시도가 중복 과금되나요?
같은 Idempotency-Key와 본문이면 원래 작업을 반환합니다.
최종 실패는 어떻게 처리하나요?
안전한 오류를 표시하고 id를 보관하며 credits_refunded로 서버 환불 완료를 확인하세요.
연동 전에 모델을 시험해 볼까요?
코드 없이 GPT Image 2 온라인 생성기에서 프롬프트와 출력 설정을 비교하세요.
GPT Image 2 온라인 사용