API Reference

전체 엔드포인트 레퍼런스 (v1.0.0). 이 문서는 에이전트가 읽는 GET /api/manifest와 같은 소스에서 자동 생성됩니다.

인증: 모든 엔드포인트는 Authorization: Bearer <mi_live_… 키> 헤더를 받습니다. BASE URL: https://imgstorage.vercel.app · 시스템/디스커버리(/api/health, /api/manifest)는 인증 불필요.

잡 API (에이전트용)

POST/api/v1/images/article-image아티클 히어로 이미지 생성 (job)

아티클 제목·요약·키워드만 주면 이미지 프롬프트를 자동 크래프팅해 히어로 이미지를 생성하고 SEO 메타데이터까지 붙입니다. 에이전트/CMS가 이미지 프롬프트를 직접 쓸 필요가 없습니다.

param	type	req	설명
title	string	필수	아티클 제목 (SEO 메타 컨텍스트로도 사용)
summary	string	—	아티클 요약/발췌 (프롬프트 크래프팅 컨텍스트)
keywords	string[]	—	핵심 키워드 (배열 또는 CSV, 최대 10개)
style	string	—	스타일 힌트 (기본: 에디토리얼 사진)
prompt	string	—	직접 프롬프트 지정 시 크래프팅 스킵
service	string	—	서비스 slug (기본: blog)
model	string	—	gemini3pro(기본) \| gemini31flash
aspect_ratio	string	—	기본 16:9
image_size	string	—	1K \| 2K(기본) \| 4K
count	number	—	변형 개수 1~3 (기본 1). 2 이상이면 images[] 배열로 응답
skip_metadata	boolean	—	SEO 메타 생성 스킵

POST/api/v1/images/optimize-metadata이미지 SEO 메타데이터 생성/갱신 (job)

이미지 하나의 SEO 메타데이터(filename/alt/title/caption)를 생성합니다. 기본은 dry-run(저장 안 함)으로 지침 실험용이고, save=true + image_id면 기존 이미지의 메타를 갱신합니다. 텍스트 오퍼레이션이라 크레딧 차감 없음.

param	type	req	설명
image_id	string	—	기존 이미지 id (image_url과 둘 중 하나 필수)
image_url	string	—	외부/CDN 이미지 URL
service	string	—	이 서비스의 SEO 지침 적용
prompt_template	string	—	지침 직접 지정 (저장 전 실험용, service보다 우선)
context	string	—	주제 컨텍스트 (예: 글 제목)
save	boolean	—	true + image_id → alt/title/caption 갱신 (기본 false = dry-run)

POST/api/v1/images/product-image-batch상품컷 세트 생성 (job)

상품 데이터 배열을 주면 일관된 스타일의 상품 연출컷 세트를 생성합니다. 모든 상품에 동일한 스타일 블록이 적용되어 세트의 톤이 유지됩니다. 부분 실패 허용 (성공분 + failures 반환). v1은 동기 처리, 최대 10개.

param	type	req	설명
products	object[]	필수	[{name(필수), attributes?(배열\|CSV, 최대 8), description?}] 최대 10개
style	string	—	세트 공통 스타일 (기본: 스튜디오 화이트 배경 상업 사진)
service	string	—	서비스 slug (기본: ecommerce)
model	string	—	gemini31flash(기본, 세트용) \| gemini3pro
aspect_ratio	string	—	기본 1:1 (상품컷)
image_size	string	—	1K \| 2K(기본) \| 4K
skip_metadata	boolean	—	SEO 메타 생성 스킵

GET/api/v1/credits잔여 크레딧 조회

현재 키/계정의 크레딧 잔액과 모델별 생성 가능 장수를 반환합니다. 에이전트가 작업 전에 잔량을 확인하고 페이스를 조절하세요. 크레딧이 부족하면 생성 API가 402를 반환합니다.

이미지 생성

POST/api/images/generate/gemini3proGemini 3 Pro 이미지 생성

텍스트 프롬프트와 참조 이미지(File API URI)로 AI 이미지를 생성합니다. 다양한 비율·해상도·thinking 모드를 지원합니다.

param	type	req	설명
prompt	string	필수	이미지 생성 프롬프트
fileUris	string[]	—	참조 이미지 Gemini File API URI 배열 (최대 14개)
aspect_ratio	string	—	비율: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size	string	—	해상도: 1K, 2K, 4K
service	string	—	서비스 slug (기본: general)
blogTitle	string	—	SEO 메타데이터 생성 시 블로그 제목 컨텍스트
thinking_enabled	boolean	—	Thinking 모드 활성화
thinking_budget	number	—	Thinking 토큰 예산 (기본 8192)
use_google_search	boolean	—	Google 검색 통합 활성화
character_id	string	—	캐릭터 UUID - 서버에서 자동으로 레퍼런스 이미지 URI를 resolve하여 병합
scene_id	string	—	씬 UUID - character_id와 함께 사용하여 씬 레퍼런스 이미지도 포함

POST/api/images/generateImagen 이미지 생성

Google Imagen 모델로 이미지를 생성합니다.

param	type	req	설명
prompt	string	필수	이미지 생성 프롬프트
service	string	—	서비스 slug

POST/api/images/generate/batch배치 이미지 생성

Imagen 모델로 여러 이미지를 배치 생성합니다.

param	type	req	설명
prompt	string	필수	이미지 생성 프롬프트
count	number	—	생성할 이미지 수
service	string	—	서비스 slug

이미지 업로드

POST/api/images/upload이미지 직접 업로드

이미지 파일을 Cloudflare Images에 직접 업로드합니다. 서버 사이드 리사이즈 없음.

param	type	req	설명
file	File	필수	업로드할 이미지 파일 (multipart/form-data)
service	string	—	서비스 slug
skip_metadata	boolean	—	SEO 메타데이터 생성 스킵

POST/api/images/upload-and-optimize이미지 업로드 + SEO 최적화

이미지 업로드 후 WebP 변환, 리사이즈, Gemini SEO 메타데이터를 자동 생성합니다.

param	type	req	설명
file	File	필수	업로드할 이미지 파일 (multipart/form-data)
blogTitle	string	—	SEO 컨텍스트용 블로그 제목
service	string	—	서비스 slug
skip_metadata	boolean	—	SEO 메타데이터 생성 스킵

POST/api/images/import-and-optimizeURL에서 이미지 가져오기 + 최적화

외부 URL의 이미지를 다운로드하여 최적화 후 업로드합니다.

param	type	req	설명
url	string	필수	이미지 URL
blogTitle	string	—	SEO 컨텍스트용 블로그 제목
service	string	—	서비스 slug
skip_metadata	boolean	—	SEO 메타데이터 생성 스킵

POST/api/images/import-and-optimize/batch배치 URL 가져오기 + 최적화

여러 URL의 이미지를 한 번에 가져와 최적화합니다.

param	type	req	설명
urls	string[]	필수	이미지 URL 배열
blogTitle	string	—	SEO 컨텍스트용 블로그 제목
service	string	—	서비스 slug
skip_metadata	boolean	—	SEO 메타데이터 생성 스킵

이미지 관리

GET/api/images이미지 목록 조회

이미지 목록을 페이지네이션으로 조회합니다. 서비스·타입 필터 지원.

param	type	req	설명
page	number	—	페이지 번호 (기본 1)
limit	number	—	페이지당 개수 (기본 20)
type	string	—	소스 타입 필터: generation, upload, import
service	string	—	서비스 slug 필터

GET/api/images/[id]이미지 상세 조회

이미지 ID로 메타데이터를 조회합니다.

param	type	req	설명
id	string	필수	이미지 ID (path parameter)

DELETE/api/images/[id]이미지 삭제

Cloudflare Images에서 이미지를 삭제하고 DB 레코드를 제거합니다.

param	type	req	설명
id	string	필수	이미지 ID (path parameter)

GET/api/images/service-tags서비스별 이미지 통계

각 서비스별 이미지 수 통계를 조회합니다.

POST/api/images/bulk이미지 벌크 작업

여러 이미지를 일괄 삭제하거나 서비스를 변경합니다. 최대 100개.

param	type	req	설명
action	string	필수	"delete" 또는 "changeService"
imageIds	string[]	필수	이미지 ID 배열 (최대 100개)
targetServiceSlug	string	—	changeService 시 대상 서비스 slug

POST/api/images/[id]/regenerate이미지 재생성 및 대체

AI 생성 이미지를 재생성하고 동일 ID로 대체합니다. action: preview(프리뷰 생성), confirm(대체 확정), discard(폐기).

param	type	req	설명
id	string	필수	이미지 ID (path parameter)
action	string	필수	"preview", "confirm", "discard"
prompt	string	—	생성 프롬프트 (preview/confirm 시)
tempId	string	—	임시 이미지 ID (confirm/discard 시)
aspect_ratio	string	—	비율 (기본: 4:3)
image_size	string	—	해상도: 1K, 2K, 4K (기본: 2K)

서비스 프로필

GET/api/images/services서비스 프로필 목록

활성 서비스 프로필 목록을 이미지 수와 함께 조회합니다. 에이전트는 이 응답으로 각 서비스의 용도, 자동 삭제 정책, 메타데이터 스킵 여부를 판단할 수 있습니다.

POST/api/images/services서비스 프로필 생성

새 서비스 프로필을 생성합니다.

param	type	req	설명
slug	string	필수	서비스 식별자 (소문자, 숫자, 하이픈)
name	string	필수	표시 이름
description	string	—	서비스 설명
prompt_summary	string	—	SEO 프롬프트 요약 (200자 이내)
seo_prompt_template	string	—	SEO 프롬프트 템플릿 ({{blogTitle}} 변수 지원)
seo_model	string	—	SEO 분석 Gemini 모델
skip_metadata_default	boolean	—	메타데이터 생성 기본 스킵 여부
retention_hours	number	—	자동 삭제 시간 (null = 영구보관)

GET/api/images/services/[slug]서비스 프로필 상세 조회

서비스 프로필 단건 조회 (전체 프롬프트 템플릿 포함).

param	type	req	설명
slug	string	필수	서비스 slug (path parameter)

PUT/api/images/services/[slug]서비스 프로필 수정

서비스 프로필을 부분 업데이트합니다.

param	type	req	설명
slug	string	필수	서비스 slug (path parameter)
name	string	—	표시 이름
prompt_summary	string	—	SEO 프롬프트 요약
seo_prompt_template	string	—	SEO 프롬프트 템플릿

DELETE/api/images/services/[slug]서비스 프로필 비활성화

서비스 프로필을 소프트 삭제합니다 (is_active = false). general 프로필은 삭제 불가.

param	type	req	설명
slug	string	필수	서비스 slug (path parameter)

시스템

GET/api/health시스템 헬스 체크

Supabase, Cloudflare, Gemini 서비스 연결 상태를 확인합니다.

GET/api/manifestAPI 카탈로그 조회

사용 가능한 모든 API 엔드포인트 목록과 파라미터 정보를 반환합니다.

GET/api/admin/usageGemini API 사용량 통계

Gemini API 토큰 사용량과 비용 통계를 조회합니다.

param	type	req	설명
view	string	—	뷰 타입: summary, daily, model
days	number	—	조회 기간 (기본 30일)

GET/api/cron/cleanup-expired만료 이미지 자동 정리

retention_hours 기반으로 만료된 이미지를 자동 삭제합니다. Cron job용.

기계용 카탈로그: GET /api/manifest — 이 페이지와 동일한 내용의 JSON입니다.