AI 에이전트 연동

imagin은 처음부터 에이전트가 호출하는 것을 전제로 설계됐습니다. 키 하나와 브리프 한 장이면 에이전트가 이미지 파이프라인을 통째로 운영합니다.

가장 빠른 길 — 에이전트 브리프

콘솔 Services → 서비스 상세 → 에이전트에게 넘기기를 누르면 ① 그 서비스 전용 API 키(scope 제한)가 발급되고 ② 도구 사용법이 담긴 브리프가 만들어집니다. 이 텍스트를 에이전트의 시스템 프롬프트나 설정에 붙여넣는 것으로 연동이 끝납니다.

agent-brief.md (요약)

# mabro imagin — 블로그 이미지 파이프라인
AUTH: Authorization: Bearer mi_live_xxxx (scope: blog)

도구:
1. 아티클 이미지:  POST /api/v1/images/article-image {title, keywords}
2. 직접 생성:      POST /api/images/generate/gemini3pro {prompt}
3. 업로드+SEO:     POST /api/images/upload-and-optimize (multipart)
4. URL 가져오기:   POST /api/images/import-and-optimize {url}
5. 메타 재생성:    POST /api/v1/images/optimize-metadata {image_id, save}

공통: imageUrl의 /public → /blog·/og·/card 교체로 크기 변형
잔량: GET /api/v1/credits · 카탈로그: GET /api/manifest

에이전트 디스커버리 워크플로우

브리프 없이도 에이전트가 스스로 파악할 수 있도록 디스커버리 엔드포인트가 공개돼 있습니다.

discovery

1. GET /api/health              시스템 정상? (인증 불필요)
2. GET /api/manifest            전체 도구 카탈로그 + 파라미터 (인증 불필요)
3. GET /api/images/services     내 서비스 목록 + promptSummary (어떤 지침인지)
4. GET /api/v1/credits          잔여 크레딧 → 작업량 판단
5. POST (원하는 도구)           실행

새 도구(배경 제거 등)가 추가되면 manifest에 나타납니다. 에이전트에게 “주기적으로 GET /api/manifest를 다시 읽으라”고 지시해두면 기능 확장을 자동으로 따라갑니다.

잔량 관리 — 402를 만나기 전에

생성은 크레딧을 차감하므로, 좋은 에이전트는 작업 전에 잔량을 확인하고 페이스를 조절합니다.

response — GET /api/v1/credits

{
  "credits": { "total": 300, "used": 150, "remaining": 150 },
  "estimatedRemainingImages": {
    "gemini-3-pro-image-preview (2K)": 0,
    "gemini-3.1-flash-image-preview (2K)": 1
  }
}

잔액 부족 시 생성 API는 402와 INSUFFICIENT_CREDITS 코드를 반환합니다. 에이전트 프롬프트에 “402를 받으면 생성을 멈추고 사용자에게 보고하라”를 넣어두는 것을 권장합니다.

에이전트에게 좋은 습관 (프롬프트에 넣을 것)

상황	지시
아티클/포스트 이미지가 필요할 때	article-image를 우선 사용 — 프롬프트를 직접 쓰지 말 것
외부 이미지 URL을 재사용할 때	import-and-optimize로 내 CDN 자산으로 변환 후 사용
본문·OG 등 크기가 필요할 때	새로 만들지 말고 imageUrl의 variant만 교체
ALT가 마음에 안 들 때	재생성 대신 optimize-metadata(save=true)로 메타만 갱신
402 응답	생성 중단, 사용자에게 잔액 보고

MCP 서버

MCP를 지원하는 에이전트(Claude Code 등)는 REST 대신 MCP 툴로 바로 연결할 수 있습니다. 별도 설치 없이 원격(HTTP)으로 붙고, 키의 scope·크레딧·테넌시가 그대로 상속됩니다.

terminal (Claude Code)

claude mcp add --transport http imagin \
  https://imgstorage.vercel.app/api/mcp \
  --header "Authorization: Bearer mi_live_..."

MCP 툴	하는 일	크레딧
`imagin_get_credits`	잔여 크레딧·모델별 생성 가능 장수	0
`imagin_search_images`	내 이미지 자산 검색	0
`imagin_create_article_image`	제목만으로 히어로 이미지 + SEO	차감
`imagin_import_image`	외부 URL → 내 CDN 자산	0
`imagin_optimize_image_seo`	SEO 메타 생성/갱신 (dry-run 기본)	0

파괴적 작업(삭제·서비스 변경)은 MCP에 노출하지 않습니다 — 콘솔에서만 가능합니다. 전체 REST 파라미터는 API Reference 참고.