이미지→프롬프트 변환 기능을 애플리케이션에 통합하면 강력한 가능성이 열립니다. 자동 설명 생성, 비주얼 검색 도구, 콘텐츠 제작 파이프라인, 비주얼 스타일 기반 추천 시스템 등을 구현할 수 있습니다. 이 기술 가이드에서는 개발자가 ImageToPrompt API를 프로젝트에 통합하기 위해 필요한 모든 것을 해설합니다.

참고: ImageToPrompt API는 Anthropic의 Claude AI로 구동되며, 이미지를 일시적으로만 처리합니다. 이미지가 서버에 저장되는 일은 절대 없습니다.

API 개요

ImageToPrompt API는 이미지/텍스트에서 AI 프롬프트로의 변환에 관한 모든 사용 사례를 커버하는 4개의 주요 엔드포인트를 제공합니다. 각 엔드포인트는 JSON 본문을 포함한 POST 요청을 수신하고, 생성된 프롬프트와 유용한 메타데이터를 포함하는 구조화된 응답을 반환합니다.

API는 Vercel의 서버리스 함수로 호스팅되어 낮은 레이턴시와 높은 가용성을 보장합니다. 이미지의 복잡도와 선택한 타겟 모델에 따라 평균 응답 시간은 5~10초입니다.

인증과 보안

API 요청에는 시크릿 키를 포함한 인증 헤더가 필요합니다. 이 키는 각 요청의 x-app-secret 헤더에 포함하여 전송합니다.

POST /api/analyze Content-Type: application/json x-app-secret: YOUR_APP_SECRET { "image": "data:image/jpeg;base64,/9j/4AAQ...", "model": "midjourney", "style": "cinematic" }

모든 통신은 HTTPS로 암호화됩니다. 이미지는 요청 본문에서 base64로 전송되며, 안전하지 않은 서드파티 서비스를 경유하지 않습니다.

사용 가능한 엔드포인트

엔드포인트 메서드 설명
/api/analyze POST 이미지를 타겟 모델용 AI 프롬프트로 변환
/api/text-to-prompt POST 텍스트 설명을 최적화된 AI 프롬프트로 변환
/api/image-to-video-prompt POST 소스 이미지에서 AI 동영상 프롬프트를 생성
/api/text-to-video-prompt POST 텍스트 설명에서 AI 동영상 프롬프트를 생성

Python 통합 예제

다음은 requests 라이브러리를 사용한 Python의 완전한 통합 예제입니다. 이 스크립트는 로컬 이미지를 base64로 인코딩하고, API에 요청을 전송한 후, 생성된 프롬프트를 표시합니다.

import requests import base64 import json def image_to_prompt(image_path, model="midjourney", style="cinematic"): """Convert a local image to an AI prompt.""" # Read and encode the image with open(image_path, "rb") as f: image_data = base64.b64encode(f.read()).decode("utf-8") # Determine MIME type ext = image_path.lower().split(".")[-1] mime_types = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"} mime = mime_types.get(ext, "jpeg") # Build the request payload = { "image": f"data:image/{mime};base64,{image_data}", "model": model, "style": style } headers = { "Content-Type": "application/json", "x-app-secret": "YOUR_APP_SECRET" } response = requests.post( "https://www.imagetoprompt.dev/api/analyze", json=payload, headers=headers, timeout=30 ) if response.status_code == 200: result = response.json() return result elif response.status_code == 429: print("Rate limit reached. Try again tomorrow.") return None else: print(f"Error {response.status_code}: {response.text}") return None # Usage result = image_to_prompt("my-photo.jpg", model="flux", style="technical") if result: print("Prompt:", result["prompt"]) print("Negative:", result.get("negative", "N/A"))

JavaScript 통합 예제

웹 애플리케이션 및 Node.js용 fetch를 사용한 예제입니다. 이 코드는 브라우저 측에서도 Node.js 18+ 서버 측에서도 동작합니다.

async function imageToPrompt(imageFile, model = "midjourney", style = "cinematic") { // Convert File to base64 const reader = new FileReader(); const base64 = await new Promise((resolve) => { reader.onload = () => resolve(reader.result); reader.readAsDataURL(imageFile); }); const response = await fetch("https://www.imagetoprompt.dev/api/analyze", { method: "POST", headers: { "Content-Type": "application/json", "x-app-secret": "YOUR_APP_SECRET" }, body: JSON.stringify({ image: base64, model: model, style: style }) }); if (response.status === 429) { throw new Error("Rate limit exceeded"); } if (!response.ok) { throw new Error(`API error: ${response.status}`); } return await response.json(); } // Usage with file input const fileInput = document.querySelector('input[type="file"]'); fileInput.addEventListener("change", async (e) => { const file = e.target.files[0]; try { const result = await imageToPrompt(file, "stable-diffusion", "technical"); console.log("Generated prompt:", result.prompt); } catch (err) { console.error("Failed:", err.message); } });

요청 파라미터

각 엔드포인트는 프롬프트 생성에 영향을 주는 특정 파라미터를 수신합니다. 다음은 메인 엔드포인트 /api/analyze의 파라미터입니다.

파라미터 타입 필수 설명
image string 예 data URI 접두사가 포함된 base64 이미지
model string 예 타겟 모델: midjourney, stable-diffusion, flux, dall-e-3, adobe-firefly, leonardo-ai, ideogram
style string 아니요 프롬프트 스타일: cinematic, technical, artistic, minimal, epic, photographic

응답 형식

API는 메인 프롬프트, 네거티브 프롬프트(해당하는 경우), 크리에이티브 변형, 비주얼 분석 메타데이터를 포함하는 구조화된 JSON 객체를 반환합니다.

{ "prompt": "cinematic portrait of a woman in golden hour light, shallow depth of field, film grain, warm tones --ar 3:2 --v 6.1 --style raw", "negative": "blurry, low quality, deformed, bad anatomy", "remix": "ethereal portrait bathed in amber sunset glow, dreamlike bokeh...", "colors": ["#D4A574", "#2C1810", "#F5E6D3", "#8B4513", "#FFD700"], "tags": ["portrait", "golden hour", "cinematic", "warm tones"], "aspectRatio": "3:2", "model": "midjourney", "style": "cinematic" }

속도 제한과 할당량

API는 Upstash Redis를 사용한 IP 주소 기반 속도 제한 시스템을 채택하고 있습니다. 현재 제한 사항은 다음과 같습니다.

할당량을 초과하면 API는 설명 메시지가 포함된 HTTP 429 코드를 반환합니다. 클라이언트 코드에 지수 백오프를 적용한 재시도 메커니즘을 구현하세요.

오류 처리

API는 오류를 보고하기 위해 표준 HTTP 코드를 사용합니다. 다음은 가장 일반적인 코드와 그 의미입니다.

코드 의미 권장 대응
200 성공 응답을 정상적으로 처리
400 잘못된 요청 이미지 포맷과 파라미터를 확인
401 미인증 x-app-secret 키를 확인
429 속도 제한 도달 할당량 리셋을 기다리거나 유료 플랜으로 업그레이드
500 서버 오류 지수 백오프로 수 초 후 재시도

고급 활용 사례

콘텐츠 생성 파이프라인

API를 콘텐츠 제작 파이프라인에 통합하여 상품 사진, 포트폴리오 이미지, 디자인 스크린샷에서 자동으로 비주얼 설명을 생성할 수 있습니다. 이를 통해 대규모로 일관된 스타일 변형을 만들 수 있습니다.

비주얼 검색 엔진

생성된 프롬프트를 시맨틱 디스크립터로 활용하여 비주얼 스타일별로 이미지를 인덱싱하고 검색할 수 있습니다. API가 반환하는 컬러, 스타일, 분위기 태그가 비주얼 유사성 검색을 위한 풍부한 인덱스를 구축합니다.

크리에이티브 교육 도구

이미지를 비주얼 요소(조명, 구도, 팔레트, 스타일)로 분해하는 교육 도구를 구축하여 아티스트와 사진작가가 이미지를 효과적으로 만드는 요소를 이해하도록 도울 수 있습니다.

SNS 자동화

비주얼에서 설명적인 캡션이나 해시태그를 자동 생성할 수 있습니다. 생성된 프롬프트에는 비주얼 콘텐츠를 상세하고 매력적으로 설명하기 위한 가장 관련성 높은 용어가 포함되어 있습니다.

지금 바로 API를 체험하세요

하루 10건의 무료 할당량으로 체험해 보세요. 온라인 도구 테스트에는 가입이 필요 없습니다.

ImageToPrompt 무료 체험 →

자주 묻는 질문

ImageToPrompt API는 무료인가요?

API는 IP 주소당 하루 10건의 무료 할당량을 제공합니다. 이 할당량은 모든 엔드포인트(image-to-prompt, text-to-prompt, image-to-video, text-to-video)에서 공유됩니다. 더 많은 요청이 필요하면 요금 페이지에서 유료 플랜을 확인하세요.

API가 지원하는 이미지 포맷은 무엇인가요?

API는 JPEG, PNG, WebP, GIF(첫 번째 프레임만) 형식의 이미지를 지원합니다. 최대 크기는 이미지당 10MB입니다. 이미지는 JSON 요청 본문에서 base64로 인코딩하여 전송합니다. 최상의 결과를 위해 512x512 픽셀 이상의 이미지를 사용하세요.

API 오류와 속도 제한은 어떻게 처리하나요?

속도 제한에 도달하면 API는 HTTP 429 코드를 반환하고 Retry-After 헤더로 재시도 타이밍을 알려줍니다. 코드에 지수 백오프를 구현하세요. 400 오류는 요청 문제(잘못된 이미지, 누락된 파라미터)를 나타내고, 500 오류는 일시적인 서버 문제를 나타냅니다.

API에 전송한 이미지는 저장되나요?

아니요. 모든 이미지는 메모리에서 일시적으로 처리되며, 서버에 저장되지 않습니다. 분석은 Claude AI에 의해 실시간으로 실행되고, 프롬프트 생성 후 데이터는 즉시 삭제됩니다. 이미지 로그는 일절 보관하지 않습니다.