API 문서

Google nano-banana-pro 기반 텍스트→이미지 / 이미지→이미지 생성 REST API.

개요

모든 요청의 기준 URL(Base URL):

• 요청/응답은 JSON (UTF-8).
• 생성은 비동기: 요청 시 job_id 를 받고 /v1/job/{id} 로 폴링.
• 결과 이미지는 https://dropshot.rebeauty.cafe/img/<파일명> 절대 URL 로 반환.
• 모델 google/nano-banana-pro · 무제한 모드(크레딧 소모 없음).

인증

생성/조회 엔드포인트는 공개 API 키를 X-Api-Key 헤더로 전달합니다.

X-Api-Key: ds_live_********************

쿠키 갱신·세션 조회 등 관리자 엔드포인트는 X-Admin-Key 헤더(또는 콘솔 로그인 세션)가 필요합니다. 키는 콘솔의 DropShot API 메뉴(🔑 키 탭)에서 확인하세요.

생성 흐름

1) POST /v1/generate  → { job_id, status:"queued", poll:"/v1/job/{id}" }   (202)
2) GET  /v1/job/{id}  → { status:"queued|processing" }   (2~3초 간격 폴링)
3) GET  /v1/job/{id}  → { status:"done", images:["https://dropshot.rebeauty.cafe/img/xxx.jpg"] }

보통 생성에 40~90초 소요(해상도·대기열에 따라 변동).

이미지 생성 POST /v1/generate

텍스트 프롬프트로 이미지를 생성(T2I).

curl -X POST https://dropshot.rebeauty.cafe/v1/generate \
  -H "X-Api-Key: ds_live_********" -H "Content-Type: application/json" \
  -d '{"prompt":"흰 대리석 위 빨간 사과, 스튜디오 조명","ratio":"1:1","resolution":"2K"}'

응답 202

{
  "ok": true, "job_id": "9aba727c2d4d4979", "status": "queued",
  "model": "google/nano-banana-pro", "ratio": "1:1", "resolution": "2K",
  "queue_depth": 1, "poll": "/v1/job/9aba727c2d4d4979"
}

이미지→이미지 POST /v1/edit

참조 이미지 URL(들)로 편집/변형 생성(I2I, 최대 14장). 참조는 http(s) URL 만 허용.

curl -X POST https://dropshot.rebeauty.cafe/v1/edit \
  -H "X-Api-Key: ds_live_********" -H "Content-Type: application/json" \
  -d '{"prompt":"배경을 밤바다로 바꿔줘","image_urls":["https://example.com/a.jpg"]}'

작업 조회 GET /v1/job/{id}

{
  "id": "9aba727c2d4d4979", "status": "done", "ok": true,
  "images": ["https://dropshot.rebeauty.cafe/img/ds_1783498706_0.jpg"],
  "count": 1, "mode": "t2i", "ratio": "1:1", "resolution": "2K",
  "gen_seconds": 75.1, "finished_at": "2026-07-08T08:18:26+00:00"
}

status: queued → processing → done | error

세션 상태 GET /v1/session 관리자

/v1/session/refresh(POST)는 브라우저를 열어 실제 재확인합니다.

curl https://dropshot.rebeauty.cafe/v1/session -H "X-Admin-Key: ds_admin_********"
→ {"ok":true,"account":"fgs_dna1","credit":24000,"logged_in":true}

쿠키 갱신 POST /v1/cookies/refresh 관리자

브라우저 쿠키(개발자도구 → Application → Cookies 의 .dropshot.io 표, 또는 Netscape cookies.txt)로 세션 갱신. AWS Cognito refreshToken·LastAuthUser 쿠키 필수.

{ "cookies": "…\t…\t.dropshot.io\t/\t2027-…\n…" }
→ {"ok":true,"validated":true,"credit":24000,"imported":{"count":11,...}}

헬스체크 GET /health

curl https://dropshot.rebeauty.cafe/health → {"ok":true,"service":"dropshot-api"}

파라미터 값

에러 코드

대기열 동작 중요

202 로 job_id 를 받아도 생성이 보장되지는 않습니다. 대기열은 나중에 온 요청을 먼저 처리하고(LIFO), 상한을 넘으면 가장 오래 기다린 작업부터 버립니다. 버려진 작업은 폴링 시 아래 상태로 확정됩니다.

GET /v1/job/{id} → { "status":"error",
                     "error":"queue_overflow: 요청이 몰려 처리하지 못했습니다. 다시 요청해 주세요." }

• 따라서 폴링에서 status:"error" 를 반드시 처리하고, 필요하면 재요청하세요.
• 응답의 queue_depth 는 현재 대기 건수일 뿐 내 순번이 아닙니다(LIFO).
• 상한은 그 키가 쓰는 계정 수 × 12 입니다.
• /v1/edit 의 image_urls 는 최대 14개까지만 쓰이고 나머지는 무시됩니다.

예제 코드

Python

import requests, time
BASE="https://dropshot.rebeauty.cafe"; KEY="ds_live_********"
h={"X-Api-Key":KEY,"Content-Type":"application/json"}
j=requests.post(f"{BASE}/v1/generate",json={"prompt":"a red apple","ratio":"1:1"},headers=h).json()
jid=j["job_id"]
while True:
    d=requests.get(f"{BASE}/v1/job/{jid}",headers=h).json()
    if d["status"] in("done","error"): break
    time.sleep(3)
print(d["images"][0] if d["status"]=="done" else d["error"])

JavaScript

const BASE="https://dropshot.rebeauty.cafe", KEY="ds_live_********";
const h={"X-Api-Key":KEY,"Content-Type":"application/json"};
const {job_id}=await (await fetch(`${BASE}/v1/generate`,{method:"POST",headers:h,
  body:JSON.stringify({prompt:"a red apple",ratio:"1:1"})})).json();
let d; do{ await new Promise(r=>setTimeout(r,3000));
  d=await (await fetch(`${BASE}/v1/job/${job_id}`,{headers:h})).json();
}while(!["done","error"].includes(d.status));
console.log(d.images?.[0] || d.error);