Ketchup API (Google Nano Banana 2) 개발자 가이드
Ketchup API 이미지 워크플로우를 위한 가이드, 샘플 페이로드, 모범 사례로 빠르게 구축하세요.
Ketchup API 요금제 보기Ketchup API 플랜과 사용량 단계를 비교해보세요.
Ketchup API 개요
Ketchup API는 예측 가능한 렌더링 품질로 제품 촬영, UI 배경, 소셜 그래픽을 지원합니다. REST 설계로 통합이 간단하며, 개인 개발자부터 엔터프라이즈 출시까지 확장됩니다.
Ketchup API 기능
- Ketchup API 모델로 프로덕션 씬에 최적화된 텍스트-이미지 생성.
- 단일 Ketchup API 요청으로 최대 5개 이미지를 사용한 참조 기반 편집.
- Ketchup API 렌더링 중에도 앱이 반응성을 유지하는 비동기 작업 큐.
- Ketchup API가 실시간으로 상태 변경을 푸시하는 웹훅 콜백.
- Ketchup API 응답을 쉽게 파싱할 수 있는 일관된 JSON 스키마.
- Ketchup API 대시보드에서 관리되는 Bearer 토큰 보안.
overview.base_url
https://api.defapi.orgoverview.api_version
v1.0.0Ketchup API 시작하기
- Ketchup API 워크스페이스를 열고 액세스 토큰을 생성하세요.
- 모든 호출에 대해 Authorization 헤더에 Ketchup API Bearer 토큰을 추가하세요.
- 프롬프트, 모드, 참조와 함께 Ketchup API 이미지 생성 엔드포인트에 POST하세요.
- 반환된 작업 ID를 저장하고 상태 엔드포인트를 폴링하거나 웹훅을 구독하세요.
- Ketchup API가 작업을 성공으로 표시하면 최종 파일을 다운로드하세요.
인증
모든 Ketchup API 요청에는 유효한 Bearer 토큰이 필요합니다. 환경별로 키를 교체하고 사용량을 자주 확인하세요.
Bearer 토큰 방식
아래와 같이 Authorization 헤더에 Ketchup API 토큰을 첨부하세요:
Authorization: Bearer <your-api-key>토큰 형식 예시
Authorization: Bearer dk-1234567890abcdef요청 샘플
curl -X POST "https://api.defapi.org/api/image/gen" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key-here" \
-d '{
"model": "google/gempix2",
"prompt": "A beautiful landscape"
}'유효한 토큰 체크리스트
- ✅ 토큰이 활성화되어 있고 만료되지 않았습니다.
- ✅ 워크스페이스에 Ketchup API 액세스가 활성화되어 있습니다.
- ✅ 계정에 남은 할당량이나 크레딧이 있습니다.
일반적인 문제
- ❌ Authorization 헤더가 누락되었습니다.
- ❌ Bearer 토큰 값이 잘못되었습니다.
- ❌ 워크스페이스가 일시 정지되었거나 토큰이 취소되었습니다.
Ketchup API 이미지 생성
Ketchup API 생성 엔드포인트로 새로운 렌더링을 만들거나 기존 자산을 수정하거나 무드보드를 혼합하세요.
엔드포인트
POST /api/image/gen요청 매개변수
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Model identifier (e.g., "google/gempix2") |
| prompt | string | Yes | Text prompt describing the image |
| images | array | No | Reference image URLs (max 4) |
| callback_url | string | No | Webhook URL for completion notifications |
코드 예시
기본 Ketchup API 프롬프트
{
"model": "google/gempix2",
"prompt": "A beautiful girl dancing in a garden"
}참조를 사용한 Ketchup API 리믹스
{
"model": "google/gempix2",
"prompt": "Put them in a basket",
"images": [
"https://cdn.openai.com/API/docs/images/body-lotion.png",
"https://cdn.openai.com/API/docs/images/soap.png"
],
"callback_url": "https://example.com/webhook/image-callback"
}응답 스키마
{
"code": 0,
"message": "ok",
"data": {
"task_id": "ta12345678-1234-1234-1234-123456789abc"
}
}오류 처리
400 - Bad Request
{"code": 1, "message": "failed", "detail": "prompt is required"}401 - Unauthorized
{"code": 1, "message": "Invalid API key"}Ketchup API 작업 상태
상태 엔드포인트를 사용하여 렌더링 진행 상황을 모니터링하고 배송 URL을 가져오세요.
엔드포인트
GET /api/task/query?task_id=<task_id>쿼리 매개변수
| Parameter | Type | Required | Description |
|---|---|---|---|
| task_id | string | Yes | Unique task identifier returned from generation endpoint |
요청 샘플
curl -X GET "https://api.defapi.org/api/task/query?task_id=ta823dfb-eaac-44fd-aec2-3e2c7ba8e071" \ -H "Authorization: Bearer your-api-key-here"
상태 코드
pending - Ketchup API가 요청을 수락하고 작업을 대기열에 추가했습니다.submitted - Ketchup API가 처리를 위해 작업을 예약했습니다.in_progress - Ketchup API가 현재 자산을 렌더링하고 있습니다.success - Ketchup API가 렌더링을 완료했으며 자산을 다운로드할 수 있습니다.failed - 오류로 인해 Ketchup API가 작업을 렌더링할 수 없습니다.오류 코드
404 - Task Not Found
{"code": 1, "message": "task not found"}401 - Unauthorized
{"code": 401, "message": "Invalid API key"}Ketchup API 데이터 모델
Ketchup API 통합에서 사용되는 요청 페이로드, 작업 응답, 웹훅 본문에 대한 자세한 스키마입니다.
ImageGenResult
Represents a generated image result.
{
"image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
}| Field | Type | Description |
|---|---|---|
| image | string | Image URL or base64 data URI |
CallbackPayload
Payload sent to the callback_url when task status changes to final states.
{
"result": [
{
"image": "https://google.datas.systems/fileSystem/response_images/287/2025/08/29/1756432513771985292_2989.png"
}
],
"status": "success",
"task_id": "ta5c9705-b8ae-4cb9-aa6f-97c4fee88c8d",
"consumed": "0.500000",
"status_reason": {
"message": null
}
}| Field | Type | Description |
|---|---|---|
| result | array | Array of ImageGenResult objects (null if failed) |
| status | string | Final task status (success/failed) |
| task_id | string | Unique task identifier |
| consumed | string | Credits consumed by the task |
| status_reason | object | Status details including error message if failed |
모델 스키마
google/gempix2Nano Banana image generation modelgoogle/gemini-2.5-flash-imageGemini 2.5 Flash image model문제 해결
Ketchup API 오류 형식, 재시도 규칙, 지원팀에 문의할 시점을 이해하세요.
HTTP 상태 코드
200
OK
Request was successful
400
Bad Request
Invalid request parameters or malformed JSON
401
Unauthorized
Invalid, missing, or expired API key
404
Not Found
Task not found or endpoint doesn't exist
500
Internal Server Error
Server-side error occurred
모범 사례
- 페이로드를 파싱하기 전에 HTTP 상태 코드를 확인하세요.
- 500 오류 후 Ketchup API 작업을 재시도할 때 지수적 백오프를 사용하세요.
- Ketchup API 지원팀이 문제를 추적할 수 있도록 요청 ID를 로그로 남기세요.
- 400 응답을 피하기 위해 프롬프트와 이미지 URL을 로컬에서 검증하세요.
- 인증이 실패하기 시작하면 Ketchup API 토큰을 교체하세요.
- 속도 제한을 준수하기 위해 작업 상태를 초당 1회 이하로 폴링하세요.
- 대량 실행 시에는 Ketchup API가 업데이트를 푸시할 수 있도록 웹훅을 사용하세요.
샘플 오류 처리 (JavaScript)
async function generateImage(prompt, apiKey) {
try {
const response = await fetch('https://api.defapi.org/api/image/gen', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`
},
body: JSON.stringify({
model: 'google/gempix2',
prompt: prompt
})
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(`API Error ${response.status}: ${errorData.message}`);
}
const data = await response.json();
return data.data.task_id;
} catch (error) {
console.error('Image generation failed:', error.message);
throw error;
}
}