{"apiName":"Mabro Image API","version":"1.0.0","baseUrl":"https://imagine.mabrolabs.com","generatedAt":"2026-07-12T14:14:19.933Z","auth":{"type":"bearer","header":"Authorization","format":"Bearer <MABRO_IMG_API_KEY>","note":"대부분의 /api/images/* 엔드포인트에 필요. system 카테고리는 인증 불필요."},"categories":{"jobs":"잡 API (에이전트용)","generation":"이미지 생성","upload":"이미지 업로드","management":"이미지 관리","services":"서비스 프로필","system":"시스템"},"endpoints":[{"method":"POST","path":"/api/v1/images/article-image","summary":"아티클 히어로 이미지 생성 (job)","description":"아티클 제목·요약·키워드만 주면 이미지 프롬프트를 자동 크래프팅해 히어로 이미지를 생성하고 SEO 메타데이터까지 붙입니다. 에이전트/CMS가 이미지 프롬프트를 직접 쓸 필요가 없습니다.","auth":"bearer","category":"jobs","params":[{"name":"title","type":"string","required":true,"description":"아티클 제목 (SEO 메타 컨텍스트로도 사용)"},{"name":"summary","type":"string","required":false,"description":"아티클 요약/발췌 (프롬프트 크래프팅 컨텍스트)"},{"name":"keywords","type":"string[]","required":false,"description":"핵심 키워드 (배열 또는 CSV, 최대 10개)"},{"name":"style","type":"string","required":false,"description":"스타일 힌트 (기본: 에디토리얼 사진)"},{"name":"prompt","type":"string","required":false,"description":"직접 프롬프트 지정 시 크래프팅 스킵"},{"name":"service","type":"string","required":false,"description":"서비스 slug (기본: blog)"},{"name":"model","type":"string","required":false,"description":"gemini3pro(기본) | gemini31flash"},{"name":"aspect_ratio","type":"string","required":false,"description":"기본 16:9"},{"name":"image_size","type":"string","required":false,"description":"1K | 2K(기본) | 4K"},{"name":"count","type":"number","required":false,"description":"변형 개수 1~3 (기본 1). 2 이상이면 images[] 배열로 응답"},{"name":"skip_metadata","type":"boolean","required":false,"description":"SEO 메타 생성 스킵"}]},{"method":"POST","path":"/api/v1/images/optimize-metadata","summary":"이미지 SEO 메타데이터 생성/갱신 (job)","description":"이미지 하나의 SEO 메타데이터(filename/alt/title/caption)를 생성합니다. 기본은 dry-run(저장 안 함)으로 지침 실험용이고, save=true + image_id면 기존 이미지의 메타를 갱신합니다. 텍스트 오퍼레이션이라 크레딧 차감 없음.","auth":"bearer","category":"jobs","params":[{"name":"image_id","type":"string","required":false,"description":"기존 이미지 id (image_url과 둘 중 하나 필수)"},{"name":"image_url","type":"string","required":false,"description":"외부/CDN 이미지 URL"},{"name":"service","type":"string","required":false,"description":"이 서비스의 SEO 지침 적용"},{"name":"prompt_template","type":"string","required":false,"description":"지침 직접 지정 (저장 전 실험용, service보다 우선)"},{"name":"context","type":"string","required":false,"description":"주제 컨텍스트 (예: 글 제목)"},{"name":"save","type":"boolean","required":false,"description":"true + image_id → alt/title/caption 갱신 (기본 false = dry-run)"}]},{"method":"POST","path":"/api/v1/images/product-image-batch","summary":"상품컷 세트 생성 (job)","description":"상품 데이터 배열을 주면 일관된 스타일의 상품 연출컷 세트를 생성합니다. 모든 상품에 동일한 스타일 블록이 적용되어 세트의 톤이 유지됩니다. 부분 실패 허용 (성공분 + failures 반환). v1은 동기 처리, 최대 10개.","auth":"bearer","category":"jobs","params":[{"name":"products","type":"object[]","required":true,"description":"[{name(필수), attributes?(배열|CSV, 최대 8), description?}] 최대 10개"},{"name":"style","type":"string","required":false,"description":"세트 공통 스타일 (기본: 스튜디오 화이트 배경 상업 사진)"},{"name":"service","type":"string","required":false,"description":"서비스 slug (기본: ecommerce)"},{"name":"model","type":"string","required":false,"description":"gemini31flash(기본, 세트용) | gemini3pro"},{"name":"aspect_ratio","type":"string","required":false,"description":"기본 1:1 (상품컷)"},{"name":"image_size","type":"string","required":false,"description":"1K | 2K(기본) | 4K"},{"name":"skip_metadata","type":"boolean","required":false,"description":"SEO 메타 생성 스킵"}]},{"method":"GET","path":"/api/v1/credits","summary":"잔여 크레딧 조회","description":"현재 키/계정의 크레딧 잔액과 모델별 생성 가능 장수를 반환합니다. 에이전트가 작업 전에 잔량을 확인하고 페이스를 조절하세요. 크레딧이 부족하면 생성 API가 402를 반환합니다.","auth":"bearer","category":"jobs","params":[]},{"method":"POST","path":"/api/images/generate/gemini3pro","summary":"Gemini 3 Pro 이미지 생성","description":"텍스트 프롬프트와 참조 이미지(File API URI)로 AI 이미지를 생성합니다. 다양한 비율·해상도·thinking 모드를 지원합니다.","auth":"bearer","category":"generation","params":[{"name":"prompt","type":"string","required":true,"description":"이미지 생성 프롬프트"},{"name":"fileUris","type":"string[]","required":false,"description":"참조 이미지 Gemini File API URI 배열 (최대 14개)"},{"name":"aspect_ratio","type":"string","required":false,"description":"비율: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9"},{"name":"image_size","type":"string","required":false,"description":"해상도: 1K, 2K, 4K"},{"name":"service","type":"string","required":false,"description":"서비스 slug (기본: general)"},{"name":"blogTitle","type":"string","required":false,"description":"SEO 메타데이터 생성 시 블로그 제목 컨텍스트"},{"name":"thinking_enabled","type":"boolean","required":false,"description":"Thinking 모드 활성화"},{"name":"thinking_budget","type":"number","required":false,"description":"Thinking 토큰 예산 (기본 8192)"},{"name":"use_google_search","type":"boolean","required":false,"description":"Google 검색 통합 활성화"},{"name":"character_id","type":"string","required":false,"description":"캐릭터 UUID - 서버에서 자동으로 레퍼런스 이미지 URI를 resolve하여 병합"},{"name":"scene_id","type":"string","required":false,"description":"씬 UUID - character_id와 함께 사용하여 씬 레퍼런스 이미지도 포함"}]},{"method":"POST","path":"/api/images/generate","summary":"Imagen 이미지 생성","description":"Google Imagen 모델로 이미지를 생성합니다.","auth":"bearer","category":"generation","params":[{"name":"prompt","type":"string","required":true,"description":"이미지 생성 프롬프트"},{"name":"service","type":"string","required":false,"description":"서비스 slug"}]},{"method":"POST","path":"/api/images/generate/batch","summary":"배치 이미지 생성","description":"Imagen 모델로 여러 이미지를 배치 생성합니다.","auth":"bearer","category":"generation","params":[{"name":"prompt","type":"string","required":true,"description":"이미지 생성 프롬프트"},{"name":"count","type":"number","required":false,"description":"생성할 이미지 수"},{"name":"service","type":"string","required":false,"description":"서비스 slug"}]},{"method":"POST","path":"/api/images/upload","summary":"이미지 직접 업로드","description":"이미지 파일을 Cloudflare Images에 직접 업로드합니다. 서버 사이드 리사이즈 없음.","auth":"bearer","category":"upload","params":[{"name":"file","type":"File","required":true,"description":"업로드할 이미지 파일 (multipart/form-data)"},{"name":"service","type":"string","required":false,"description":"서비스 slug"},{"name":"skip_metadata","type":"boolean","required":false,"description":"SEO 메타데이터 생성 스킵"}]},{"method":"POST","path":"/api/images/upload-and-optimize","summary":"이미지 업로드 + SEO 최적화","description":"이미지 업로드 후 WebP 변환, 리사이즈, Gemini SEO 메타데이터를 자동 생성합니다.","auth":"bearer","category":"upload","params":[{"name":"file","type":"File","required":true,"description":"업로드할 이미지 파일 (multipart/form-data)"},{"name":"blogTitle","type":"string","required":false,"description":"SEO 컨텍스트용 블로그 제목"},{"name":"service","type":"string","required":false,"description":"서비스 slug"},{"name":"skip_metadata","type":"boolean","required":false,"description":"SEO 메타데이터 생성 스킵"}]},{"method":"POST","path":"/api/images/import-and-optimize","summary":"URL에서 이미지 가져오기 + 최적화","description":"외부 URL의 이미지를 다운로드하여 최적화 후 업로드합니다.","auth":"bearer","category":"upload","params":[{"name":"url","type":"string","required":true,"description":"이미지 URL"},{"name":"blogTitle","type":"string","required":false,"description":"SEO 컨텍스트용 블로그 제목"},{"name":"service","type":"string","required":false,"description":"서비스 slug"},{"name":"skip_metadata","type":"boolean","required":false,"description":"SEO 메타데이터 생성 스킵"}]},{"method":"POST","path":"/api/images/import-and-optimize/batch","summary":"배치 URL 가져오기 + 최적화","description":"여러 URL의 이미지를 한 번에 가져와 최적화합니다.","auth":"bearer","category":"upload","params":[{"name":"urls","type":"string[]","required":true,"description":"이미지 URL 배열"},{"name":"blogTitle","type":"string","required":false,"description":"SEO 컨텍스트용 블로그 제목"},{"name":"service","type":"string","required":false,"description":"서비스 slug"},{"name":"skip_metadata","type":"boolean","required":false,"description":"SEO 메타데이터 생성 스킵"}]},{"method":"GET","path":"/api/images","summary":"이미지 목록 조회","description":"이미지 목록을 페이지네이션으로 조회합니다. 서비스·타입 필터 지원.","auth":"bearer","category":"management","params":[{"name":"page","type":"number","required":false,"description":"페이지 번호 (기본 1)"},{"name":"limit","type":"number","required":false,"description":"페이지당 개수 (기본 20)"},{"name":"type","type":"string","required":false,"description":"소스 타입 필터: generation, upload, import"},{"name":"service","type":"string","required":false,"description":"서비스 slug 필터"}],"responseFields":[{"name":"id","type":"string","description":"이미지 고유 ID (Cloudflare Image ID)"},{"name":"image_url","type":"string","description":"이미지 공개 URL (variant 변경 가능: public, full, blog, og, card, gallery, avatar)"},{"name":"source_type","type":"string","description":"소스 타입: generation, upload, import"},{"name":"filename","type":"string|null","description":"SEO 최적화 파일명"},{"name":"alt_text","type":"string|null","description":"SEO ALT 텍스트"},{"name":"image_title","type":"string|null","description":"이미지 제목 (한국어)"},{"name":"caption","type":"string|null","description":"이미지 캡션 (한국어)"},{"name":"service_id","type":"string|null","description":"서비스 프로필 ID (FK)"},{"name":"created_at","type":"string","description":"생성 일시 (ISO 8601)"}]},{"method":"GET","path":"/api/images/[id]","summary":"이미지 상세 조회","description":"이미지 ID로 메타데이터를 조회합니다.","auth":"bearer","category":"management","params":[{"name":"id","type":"string","required":true,"description":"이미지 ID (path parameter)"}]},{"method":"DELETE","path":"/api/images/[id]","summary":"이미지 삭제","description":"Cloudflare Images에서 이미지를 삭제하고 DB 레코드를 제거합니다.","auth":"bearer","category":"management","params":[{"name":"id","type":"string","required":true,"description":"이미지 ID (path parameter)"}]},{"method":"GET","path":"/api/images/service-tags","summary":"서비스별 이미지 통계","description":"각 서비스별 이미지 수 통계를 조회합니다.","auth":"bearer","category":"management","params":[]},{"method":"POST","path":"/api/images/bulk","summary":"이미지 벌크 작업","description":"여러 이미지를 일괄 삭제하거나 서비스를 변경합니다. 최대 100개.","auth":"bearer","category":"management","params":[{"name":"action","type":"string","required":true,"description":"\"delete\" 또는 \"changeService\""},{"name":"imageIds","type":"string[]","required":true,"description":"이미지 ID 배열 (최대 100개)"},{"name":"targetServiceSlug","type":"string","required":false,"description":"changeService 시 대상 서비스 slug"}]},{"method":"POST","path":"/api/images/[id]/regenerate","summary":"이미지 재생성 및 대체","description":"AI 생성 이미지를 재생성하고 동일 ID로 대체합니다. action: preview(프리뷰 생성), confirm(대체 확정), discard(폐기).","auth":"bearer","category":"management","params":[{"name":"id","type":"string","required":true,"description":"이미지 ID (path parameter)"},{"name":"action","type":"string","required":true,"description":"\"preview\", \"confirm\", \"discard\""},{"name":"prompt","type":"string","required":false,"description":"생성 프롬프트 (preview/confirm 시)"},{"name":"tempId","type":"string","required":false,"description":"임시 이미지 ID (confirm/discard 시)"},{"name":"aspect_ratio","type":"string","required":false,"description":"비율 (기본: 4:3)"},{"name":"image_size","type":"string","required":false,"description":"해상도: 1K, 2K, 4K (기본: 2K)"}]},{"method":"GET","path":"/api/images/services","summary":"서비스 프로필 목록","description":"활성 서비스 프로필 목록을 이미지 수와 함께 조회합니다. 에이전트는 이 응답으로 각 서비스의 용도, 자동 삭제 정책, 메타데이터 스킵 여부를 판단할 수 있습니다.","auth":"bearer","category":"services","params":[],"responseFields":[{"name":"slug","type":"string","description":"서비스 식별자 (API 호출 시 service 파라미터로 사용)"},{"name":"name","type":"string","description":"서비스 표시 이름"},{"name":"description","type":"string","description":"서비스 설명"},{"name":"promptSummary","type":"string|null","description":"SEO 프롬프트 요약 (서비스가 어떤 메타데이터를 생성하는지 한 줄 설명)"},{"name":"seoModel","type":"string|null","description":"SEO 분석에 사용하는 Gemini 모델 (null이면 기본 gemini-2.5-flash)"},{"name":"skipMetadataDefault","type":"boolean","description":"true면 이 서비스는 기본적으로 SEO 메타데이터를 생성하지 않음"},{"name":"retentionHours","type":"number|null","description":"자동 삭제까지 시간 (null = 영구보관, 0.5 = 30분 후 삭제)"},{"name":"imageCount","type":"number","description":"이 서비스에 속한 이미지 수"}]},{"method":"POST","path":"/api/images/services","summary":"서비스 프로필 생성","description":"새 서비스 프로필을 생성합니다.","auth":"bearer","category":"services","params":[{"name":"slug","type":"string","required":true,"description":"서비스 식별자 (소문자, 숫자, 하이픈)"},{"name":"name","type":"string","required":true,"description":"표시 이름"},{"name":"description","type":"string","required":false,"description":"서비스 설명"},{"name":"prompt_summary","type":"string","required":false,"description":"SEO 프롬프트 요약 (200자 이내)"},{"name":"seo_prompt_template","type":"string","required":false,"description":"SEO 프롬프트 템플릿 ({{blogTitle}} 변수 지원)"},{"name":"seo_model","type":"string","required":false,"description":"SEO 분석 Gemini 모델"},{"name":"skip_metadata_default","type":"boolean","required":false,"description":"메타데이터 생성 기본 스킵 여부"},{"name":"retention_hours","type":"number","required":false,"description":"자동 삭제 시간 (null = 영구보관)"}]},{"method":"GET","path":"/api/images/services/[slug]","summary":"서비스 프로필 상세 조회","description":"서비스 프로필 단건 조회 (전체 프롬프트 템플릿 포함).","auth":"bearer","category":"services","params":[{"name":"slug","type":"string","required":true,"description":"서비스 slug (path parameter)"}]},{"method":"PUT","path":"/api/images/services/[slug]","summary":"서비스 프로필 수정","description":"서비스 프로필을 부분 업데이트합니다.","auth":"bearer","category":"services","params":[{"name":"slug","type":"string","required":true,"description":"서비스 slug (path parameter)"},{"name":"name","type":"string","required":false,"description":"표시 이름"},{"name":"prompt_summary","type":"string","required":false,"description":"SEO 프롬프트 요약"},{"name":"seo_prompt_template","type":"string","required":false,"description":"SEO 프롬프트 템플릿"}]},{"method":"DELETE","path":"/api/images/services/[slug]","summary":"서비스 프로필 비활성화","description":"서비스 프로필을 소프트 삭제합니다 (is_active = false). general 프로필은 삭제 불가.","auth":"bearer","category":"services","params":[{"name":"slug","type":"string","required":true,"description":"서비스 slug (path parameter)"}]},{"method":"GET","path":"/api/characters","summary":"캐릭터 목록 조회","description":"활성 캐릭터 목록을 조회합니다. 각 캐릭터의 이미지 수, 씬 수 포함.","auth":"bearer","category":"character","params":[]},{"method":"POST","path":"/api/characters","summary":"캐릭터 생성","description":"새 캐릭터를 생성합니다.","auth":"bearer","category":"character","params":[{"name":"name","type":"string","required":true,"description":"캐릭터 이름"},{"name":"description","type":"string","required":false,"description":"캐릭터 설명 (외모, 특징)"},{"name":"style_notes","type":"string","required":false,"description":"스타일 참고사항"}]},{"method":"GET","path":"/api/characters/[id]","summary":"캐릭터 상세 조회","description":"캐릭터 상세 정보 + 레퍼런스 이미지 + 씬 목록을 조회합니다.","auth":"bearer","category":"character","params":[{"name":"id","type":"string","required":true,"description":"캐릭터 UUID (path parameter)"}]},{"method":"POST","path":"/api/characters/[id]/resolve-uris","summary":"캐릭터 레퍼런스 URI resolve","description":"캐릭터+씬의 레퍼런스 이미지를 Gemini File API URI로 변환합니다. 생성 API의 character_id 파라미터를 사용하면 자동으로 호출됩니다.","auth":"bearer","category":"character","params":[{"name":"id","type":"string","required":true,"description":"캐릭터 UUID (path parameter)"},{"name":"sceneId","type":"string","required":false,"description":"씬 UUID"},{"name":"characterImageLimit","type":"number","required":false,"description":"캐릭터 이미지 제한 (기본 10)"},{"name":"sceneImageLimit","type":"number","required":false,"description":"씬 이미지 제한 (기본 4)"}]},{"method":"POST","path":"/api/characters/[id]/images","summary":"캐릭터 레퍼런스 이미지 추가","description":"캐릭터에 레퍼런스 이미지를 추가합니다 (최대 14개). 첫 이미지는 자동으로 아바타가 됩니다. 두 방식 지원: multipart/form-data의 file 바이너리, 또는 application/json의 image_url(서버가 URL에서 다운로드). 순수 API 워크플로우에서는 image_url 방식이 편리합니다.","auth":"bearer","category":"character","params":[{"name":"id","type":"string","required":true,"description":"캐릭터 UUID (path parameter)"},{"name":"image_url","type":"string","required":false,"description":"JSON 요청 시 이미지 URL (image/* content-type, 최대 20MB). file과 택일"},{"name":"file","type":"file","required":false,"description":"multipart 요청 시 이미지 바이너리. image_url과 택일"},{"name":"label","type":"string","required":false,"description":"이미지 라벨 (예: front, side)"}]},{"method":"GET","path":"/api/health","summary":"시스템 헬스 체크","description":"Supabase, Cloudflare, Gemini 서비스 연결 상태를 확인합니다.","auth":"none","category":"system","params":[]},{"method":"GET","path":"/api/manifest","summary":"API 카탈로그 조회","description":"사용 가능한 모든 API 엔드포인트 목록과 파라미터 정보를 반환합니다.","auth":"none","category":"system","params":[]},{"method":"GET","path":"/api/admin/usage","summary":"Gemini API 사용량 통계","description":"Gemini API 토큰 사용량과 비용 통계를 조회합니다.","auth":"none","category":"system","params":[{"name":"view","type":"string","required":false,"description":"뷰 타입: summary, daily, model"},{"name":"days","type":"number","required":false,"description":"조회 기간 (기본 30일)"}]},{"method":"GET","path":"/api/cron/cleanup-expired","summary":"만료 이미지 자동 정리","description":"retention_hours 기반으로 만료된 이미지를 자동 삭제합니다. Cron job용.","auth":"cron_secret","category":"system","params":[]}]}