SAM API 가이드

SOONSOON AI Manager는 다중 AI 프로바이더를 통합하여 텍스트 생성, 이미지 생성 및 편집 기능을 제공하는 통합 API 플랫폼입니다.

🎉 새로운 기능! Gemini 2.5 Flash Image Preview로 이미지 편집 및 스타일 변경이 가능합니다.

주요 기능

🤖 텍스트 생성

Google Gemini, AWS Claude 모델로 고품질 텍스트 생성

대화형 AI 채팅
코드 생성 및 리뷰
추론 과정 포함 모델

🎨 이미지 생성

텍스트 프롬프트로 고품질 이미지 생성

Gemini 2.5 Flash NEW
AWS Nova Canvas
Stable Diffusion Ultra

✂️ 이미지 편집

기존 이미지를 업로드하여 AI로 편집

스타일 변경 (만화, 수채화 등)
배경 제거 및 변경
색상 및 밝기 조정

⚡ 빠른 시작

💡 시작하기: 관리자에게 API 키를 요청하거나 계정을 생성하세요.

1분 내에 시작하기

# 1. API 키 받기 (계정 생성 후 대시보드에서)
# 관리자에게 문의하여 API 키를 받으세요

# 2. 텍스트 생성 테스트
curl -X POST https://api.soonsoon.ai/generate/text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "messages": [{"role": "user", "content": "안녕하세요!"}],
    "model_id": "gemini-2.0-flash-lite",
    "provider": "gemini-text"
  }'

# 3. 이미지 생성 테스트
curl -X POST https://api.soonsoon.ai/create/image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "prompt": "귀여운 고양이",
    "model_id": "gemini-2.5-flash-image-preview",
    "provider": "gemini-image"
  }'

import requests

# API 설정
BASE_URL = "https://api.soonsoon.ai"
API_KEY = "YOUR_API_KEY"  # 대시보드에서 받은 API 키
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 텍스트 생성
response = requests.post(f"{BASE_URL}/generate/text", 
    headers=headers,
    json={
        "messages": [{"role": "user", "content": "안녕하세요!"}],
        "model_id": "gemini-2.0-flash-lite",
        "provider": "gemini-text"
    }
)
print(response.json())

# 이미지 생성
response = requests.post(f"{BASE_URL}/create/image",
    headers=headers,
    json={
        "prompt": "귀여운 고양이",
        "model_id": "gemini-2.5-flash-image-preview",
        "provider": "gemini-image"
    }
)
result = response.json()
print(f"이미지 생성 성공: {len(result.get('images', []))}개")

const API_KEY = 'YOUR_API_KEY'; // 대시보드에서 받은 API 키
const BASE_URL = 'https://api.soonsoon.ai';

// 텍스트 생성
async function generateText() {
    const response = await fetch(`${BASE_URL}/generate/text`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY
        },
        body: JSON.stringify({
            messages: [{role: 'user', content: '안녕하세요!'}],
            model_id: 'gemini-2.0-flash-lite',
            provider: 'gemini-text'
        })
    });
    const result = await response.json();
    console.log(result);
}

// 이미지 생성
async function generateImage() {
    const response = await fetch(`${BASE_URL}/create/image`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY
        },
        body: JSON.stringify({
            prompt: '귀여운 고양이',
            model_id: 'gemini-2.5-flash-image-preview',
            provider: 'gemini-image'
        })
    });
    const result = await response.json();
    console.log(`이미지 생성 성공: ${result.images?.length || 0}개`);
}

generateText();
generateImage();

🔐 인증

모든 API 요청에는 X-API-Key 헤더가 필요합니다.

curl -H "X-API-Key: your_api_key_here" https://api.soonsoon.ai/providers

API 키 받기

https://api.soonsoon.ai 에 로그인
대시보드에서 API 키 확인
헤더에 X-API-Key로 추가

🔗 API 엔드포인트

메소드	엔드포인트	설명	인증
GET	`/providers`	프로바이더 목록 조회	✓ API Key
GET	`/models/{provider}`	모델 목록 조회	✓ API Key
POST	`/generate/text`	텍스트 생성	✓ API Key
POST	`/create/image`	이미지 생성	✓ API Key
POST	`/generate/image`	이미지 분석/편집	✓ API Key

🔌 프로바이더

GET /providers

요청 예시

curl -H "X-API-Key: your_api_key" https://api.soonsoon.ai/providers

응답 예시

{
  "providers": [
    "gemini-text",
    "gemini-image", 
    "aws-bedrock-text",
    "aws-bedrock-image"
  ]
}

지원 프로바이더

🤖 Gemini Text

gemini-text

Google Gemini 텍스트 생성 모델

🖼️ Gemini Image

gemini-image

Google Gemini 이미지 생성/분석 모델

📝 AWS Bedrock Text

aws-bedrock-text

AWS Bedrock Claude 텍스트 모델

🎨 AWS Bedrock Image

aws-bedrock-image

AWS Nova Canvas, Stable Diffusion

🎯 모델

GET /models/{provider}

요청 예시

curl -H "X-API-Key: your_api_key" https://api.soonsoon.ai/models/gemini-image

응답 예시

{
  "models": [
    "gemini-2.5-flash-image-preview",
    "gemini-2.0-flash-preview-image-generation",
    "imagen-4.0-generate-preview-06-06"
  ]
}

💬 텍스트 생성

POST /generate/text

요청 형식

{
  "messages": [
    {"role": "user", "content": "안녕하세요!"}
  ],
  "model_id": "gemini-2.0-flash-lite",
  "provider": "gemini-text",
  "stream": false,
  "include_reasoning": false
}

cURL 예시

curl -X POST https://api.soonsoon.ai/generate/text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "messages": [{"role": "user", "content": "Python으로 Hello World 출력하는 코드 작성해줘"}],
    "model_id": "gemini-2.0-flash-lite",
    "provider": "gemini-text"
  }'

🎨 이미지 생성

POST /create/image

요청 형식

{
  "prompt": "아름다운 일몰 풍경",
  "model_id": "gemini-2.5-flash-image-preview",
  "provider": "gemini-image"
}

cURL 예시

curl -X POST https://api.soonsoon.ai/create/image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "prompt": "귀여운 고양이가 공원에서 뛰어노는 모습",
    "model_id": "gemini-2.5-flash-image-preview",
    "provider": "gemini-image"
  }'

✂️ 이미지 편집

POST /generate/image

요청 형식

{
  "prompt": "이 이미지를 만화 스타일로 바꿔줘",
  "image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
  "model_id": "gemini-2.5-flash-image-preview",
  "provider": "gemini-image"
}

🎯 모델 레퍼런스

Gemini 텍스트 모델

모델 ID	설명	특징
`gemini-2.0-flash-lite`	빠른 응답 모델	높은 속도, 비용 효율적
`gemini-2.0-flash-exp`	실험적 기능 모델	최신 기능, 베타 상태
`gemini-2.0-flash-thinking-exp` BETA	추론 과정 포함	사고 과정 노출, 논리적 추론

Gemini 이미지 모델

모델 ID	설명	기능
`gemini-2.5-flash-image-preview` NEW	이미지 편집/생성 전문	이미지 생성, 편집, 스타일 변경
`gemini-2.0-flash-preview-image-generation`	이미지 생성 모델	텍스트에서 이미지 생성
`imagen-4.0-generate-preview-06-06`	Imagen 4.0 고품질	고해상도 이미지 생성

📤 이미지 업로드

💡 팁: 이미지 편집은 gemini-2.5-flash-image-preview 모델을 사용하는 것이 가장 좋은 결과를 얻을 수 있습니다.

Base64 변환 방법

// HTML 파일 업로드 입력
<input type="file" id="imageInput" accept="image/*">
<button onclick="uploadAndEdit()">이미지 편집</button>

// JavaScript 코드
function fileToBase64(file) {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => resolve(reader.result);
        reader.onerror = error => reject(error);
    });
}

async function uploadAndEdit() {
    const fileInput = document.getElementById('imageInput');
    const file = fileInput.files[0];
    
    if (!file) {
        alert('이미지를 선택해주세요.');
        return;
    }
    
    // 이미지를 Base64로 변환
    const base64 = await fileToBase64(file);
    
    // API 호출
    const response = await fetch('https://api.soonsoon.ai/generate/image', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'YOUR_API_KEY'
        },
        body: JSON.stringify({
            prompt: '이 사진을 만화 스타일로 바꿔줘',
            image_data: base64,
            model_id: 'gemini-2.5-flash-image-preview',
            provider: 'gemini-image'
        })
    });
    
    const result = await response.json();
    console.log('편집 결과:', result);
}

import base64
import requests

def image_to_base64(image_path):
    """이미지 파일을 Base64로 변환"""
    with open(image_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
        return f"data:image/jpeg;base64,{encoded_string}"

def edit_image(image_path, prompt, api_key):
    """이미지 편집 요청"""
    # 이미지를 Base64로 변환
    image_base64 = image_to_base64(image_path)
    
    response = requests.post(
        'https://api.soonsoon.ai/generate/image',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': api_key
        },
        json={
            'prompt': prompt,
            'image_data': image_base64,
            'model_id': 'gemini-2.5-flash-image-preview',
            'provider': 'gemini-image'
        }
    )
    
    return response.json()

# 사용 예시
result = edit_image(
    'my_photo.jpg', 
    '이 사진을 수채화 스타일로 바꿔줘',
    'YOUR_API_KEY'
)

# 결과 이미지 저장
if 'images' in result and result['images']:
    edited_image = base64.b64decode(result['images'][0])
    with open('edited_photo.jpg', 'wb') as f:
        f.write(edited_image)
    print('편집된 이미지가 edited_photo.jpg로 저장되었습니다.')

#!/bin/bash

# 이미지 파일을 Base64로 변환
IMAGE_PATH="my_photo.jpg"
API_KEY="YOUR_API_KEY"

# Base64 변환
IMAGE_BASE64=$(base64 -i "$IMAGE_PATH")
IMAGE_DATA="data:image/jpeg;base64,$IMAGE_BASE64"

# API 호출
curl -X POST https://api.soonsoon.ai/generate/image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{
    \"prompt\": \"이 사진을 만화 스타일로 바꿔줘\",
    \"image_data\": \"$IMAGE_DATA\",
    \"model_id\": \"gemini-2.5-flash-image-preview\",
    \"provider\": \"gemini-image\"
  }" \
  -o response.json

echo "응답이 response.json에 저장되었습니다."

이미지 편집 프롬프트 예시

🎨 스타일 변경

"이 사진을 만화 스타일로 바꿔줘"
"수채화 스타일로 변환해줘"
"픽셀 아트 스타일로 만들어줘"

🌈 색상 조정

"이 이미지를 더 밝게 만들어줘"
"색상을 따뜻하게 조정해줘"
"흑백으로 바꿔줘"

🏭 배경 변경

"배경을 바다로 바꿔줘"
"배경을 투명하게 만들어줘"
"배경을 블러 처리해줘"

Claude Vision (AWS Bedrock) NEW

Claude 모델도 이미지 분석 기능을 지원합니다. 텍스트 생성 API에 image_data 파라미터를 추가하면 됩니다.

curl -X POST https://api.soonsoon.ai/generate/text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "messages": [{"role": "user", "content": "이 이미지에 무엇이 있나요?"}],
    "model_id": "anthropic.claude-sonnet-4-5-20250929-v1:0",
    "provider": "aws-bedrock-text",
    "image_data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
  }'

💡 팁: Claude Vision은 이미지 분석, 설명, OCR 등에 훌륭합니다. 이미지 편집은 Gemini 2.5 Flash를 사용하세요.

💻 코드 예제

Python 완전 예제

import requests
import base64

# API 설정
BASE_URL = "https://api.soonsoon.ai"
API_KEY = "your_api_key_here"
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 1. 프로바이더 목록 조회
response = requests.get(f"{BASE_URL}/providers", headers=headers)
providers = response.json()["providers"]
print("사용 가능한 프로바이더:", providers)

# 2. 텍스트 생성
text_data = {
    "messages": [{"role": "user", "content": "AI에 대해 설명해줘"}],
    "model_id": "gemini-2.0-flash-lite",
    "provider": "gemini-text"
}
response = requests.post(f"{BASE_URL}/generate/text", headers=headers, json=text_data)
print("생성된 텍스트:", response.json())

# 3. 이미지 생성
image_data = {
    "prompt": "미래도시의 모습",
    "model_id": "gemini-2.5-flash-image-preview",
    "provider": "gemini-image"
}
response = requests.post(f"{BASE_URL}/create/image", headers=headers, json=image_data)
result = response.json()

# Base64 이미지를 파일로 저장
if "images" in result and result["images"]:
    image_base64 = result["images"][0]
    with open("generated_image.jpg", "wb") as f:
        f.write(base64.b64decode(image_base64))
    print("이미지가 generated_image.jpg로 저장되었습니다.")

🔧 문제 해결

🚫 인증 오류

401 Unauthorized - API 키가 잘못되었거나 만료되었습니다.

API 키가 올바른지 확인
X-API-Key 헤더가 올바르게 설정되었는지 확인
대시보드에서 새 API 키 생성

🚫 권한 오류

403 Forbidden - 해당 모델이나 프로바이더에 대한 접근 권한이 없습니다.

관리자에게 모델 접근 권한 요청
사용 가능한 모델 목록 확인: GET /models/{provider}

⏱️ 타임아웃 오류

Timeout - 요청 처리 시간이 초과되었습니다.

이미지 크기를 줄여서 다시 시도
더 간단한 프롬프트 사용
잠시 후 다시 시도

⚠️ 제한사항

사용량 제한

제한 유형	기본값	최대값
일일 토큰 사용량	100,000	1,000,000
일일 이미지 생성	50	500
API 키 수	1	10

파일 크기 제한

이미지 업로드: 최대 10MB
지원 형식: JPEG, PNG, GIF, WebP
최대 해상도: 4096x4096 픽셀

📋 응답 구조

🔄 표준화된 응답: 모든 프로바이더가 일관된 응답 구조를 반환합니다.

텍스트 생성 응답

{
  "response": "생성된 텍스트 내용",
  "model_id": "gemini-2.0-flash-lite",
  "provider": "gemini-text",
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 50,
    "totalTokenCount": 60
  }
}

이미지 생성 응답

{
  "status": "success",
  "images": ["base64_encoded_image_data"],
  "prompt": "사용된 프롬프트",
  "model_id": "gemini-2.5-flash-image-preview",
  "provider": "gemini-image"
}

응답 필드 설명

필드	타입	설명
`response`	string	생성된 텍스트 (텍스트 생성 API만)
`images`	array	Base64 인코딩된 이미지 배열 (이미지 생성 API만)
`model_id`	string	사용된 모델 ID
`provider`	string	사용된 프로바이더명
`usageMetadata`	object	토큰 사용량 정보

📝 변경사항

v4.0.1 (2024-01-16) LATEST

🔄 응답 구조 표준화 - 모든 프로바이더가 일관된 응답 형식 반환
🔧 Gemini Text 프로바이더 응답 구조 개선
📊 프론트엔드 호환성 향상

v4.0.0 (2024-01-15)

✨ Gemini 2.5 Flash Image Preview 모델 추가
✨ 이미지 편집 및 스타일 변경 기능
🔧 모델 권한 시스템 개선
📊 상세한 API 가이드 문서 추가
🐛 다양한 버그 수정 및 성능 개선

v3.2.1 (2024-01-10)

🔧 AWS Bedrock 모델 안정성 개선
📊 사용량 추적 정확도 향상
🐛 이미지 업로드 오류 수정

v3.2.0 (2024-01-05)

✨ Azure OpenAI 모델 지원 추가
✨ 사용자별 일일 사용량 제한 기능
🔐 API 키 관리 시스템 개선