상위 문서로 이동 : AI Wiki

API의 엔드포인트 목록과 기능 설명

Endpoint	Method	설명
`/v1/generate`	POST	텍스트 프롬프트를 입력받아 이미지를 생성
`/healthcheck`	GET	서버 상태를 확인 (GCP 이용하므로 check가 필요하다고 판단됨)
`/info`	GET	사용 중인 모델 정보 및 설정 반환 (서버 버전, 해상도 등)

흐름도

클라이언트 ──▶ FastAPI 서버
               └── User Input 수신 (이미지 + 텍스트)

               └── Image-to-Text 모델 실행
                   └── 이미지에서 물품 및 텍스트 정보 추출

               └── Queue 판별
                   └── 데스크 이미지인지 판단

                   └── Yes일 경우:
                       └── Prompt 구성 (Image + Text + LoRA)
                       └── Prompt Engineering 적용
                       └── Stable Diffusion 모델로 합성 이미지 생성

                   └── 아니거나 오류 발생 시:
                       └── Naver Shopping API 호출
                       └── 최저가 링크 및 물품 URL 확보

               └── 최종 이미지 S3에 저장
               └── S3 이미지 URL 생성

클라이언트 ◀── 응답

`generate` 입⋅출력 명세

/generate - POST

{
  "initial_image_url": "https://bucket.s3.amazonaws.com/images/12.png",
}

1. initial_image_url

type : string

S3에 저장된 원본 이미지의 URL

2. prompt

type : string

생성하고 싶은 이미지에 대한 설명
a realistic image : AI가 실제처럼 보이도록 자연스럽게 합성해달라는 의도전달
aesthetically matches and complements : 사진 속 데스크의 톤, 조명, 컬러, 스타일에 맞춰 조화롭게 구성해달라는 요청

3. negative Prompt

type : string

피하고 싶은 이미지 특성
흐릿하거나 왜곡된 이미지 방지 : blurry, low resolution, distorted, deformed
사람 제거 : people, human
비현실적 스타일 배제 : cartoon, anime, painting
배경/노이즈 제어 : clutter, messy background, bad lighting
동일한 물체가 반복되는 현상 억제 : duplicate, twin, cloned

4. num_inference_steps

type : int

디퓨전 과정의 스텝 수
defalut: 50

5. guidance_scale

type : float

텍스트 가이던스 강도
defalut: 7.5

6. height, width

type : int

출력 이미지 크기
defalut: 1024, 1024

FastAPI 설계 예시

@app.post("/generate")
async def generate_image(req: PromptRequest):
    image = run_diffusion(req.prompt)
    buffer = BytesIO()
    image.save(buffer, format="PNG")
    buffer.seek(0)
    
    image_url = upload_to_s3(buffer, bucket_name="bucket")
    
    return {"image_url": image_url}

`/generate` 응답 예시

{
  "initial_image_url": "https://bucket.s3.amazonaws.com/images/12.png",
  "processed_image_url": "https://bucket.s3.amazonaws.com/images/123.png",
  "마우스": [
    {
      "title": "shopping mall title",
      "price": "21990원",
      "mall": "네이버",
      "category3": "마우스",
      "category4": "유선마우스",
      "link": "https://search.shopping.naver.com/catalog/...",
      "image": "https://... .jpg"
    },
    {
      ...
    },
    {
      ...
    }
  ],
  "item 2": [
    {
      "title": "shopping mall item title",
      "price": "N원",
      "mall": "mall name",
      "category3": "하위 카테고리2",
      "category4": "하위 카테고리1",
      "link": "shopping mall link",
      "image": "item image url"
    },
    {
      ...
    },
    {
      ...
    }
  ],
  ...
}

1. initial_image_url

type : string

S3에 저장된 원본 이미지의 URL

2. processed_image_url

type : string

AI모델을 이용한 합성된 이미지

3. Item_i

type : list

추천된 아이템 이름, 아이템에 대한 세부정보 포함

title: 쇼핑몰 판매 페이지의 title
type: string
price: 해당 제품의 가격
type: string
mall: 쇼핑몰 이름(쇼핑몰이 없으면 네이버로 return)
type: string
category3: 하위 카테고리2 (ex. 마우스)
type: string
category4: 하위 카테고리1 (ex. 유선마우스)
type: string
link: 상품 판매 페이지 링크
type: string
image: 상품 대표 이미지
type: string

오류 처리 방안 및 예외 사항

유효성 검사(Validation)

prompt가 비어 있거나(""), height와 width값이 비정상적으로 큰 경우(예: 8192 이상의 크기)
반환 코드 및 메세지: 400(Bad Request), 422(Unprocessable Entity), 500(Internal Server Error)

400(Bad Request))

{ 
  "detail" : "Prompt must not be empty."
}

422(Unprocessable Entity))

{
  "error_code" : "INVALID_INPUT"
  "message" : "Guidance scale cannot be negative."
}

500(Internal Server Error)

{
  "error_code": "S3_UPLOAD_FAILED",
  "message": "Failed to upload image to S3."
}

API 버전 관리(Versioning)

변경 가능성: 추후 API 응답 구조 또는 파라미터가 변경될 가능성이 있다면, 버전 관리를 고려해볼 수 있다.
- 예: /v1/generate, /v2/generate와 같이 엔드포인트 버전 표기
이때 명세서에도 **버전별 변경점(Change Log)**과 마이그레이션 가이드를 첨부하면 사용자에게 도움이 된다.

고려사항

이미지 파일명 규칙
- 예) UUID 등을 사용해 난수화
- 타임스탬프, 혹은 “유저ID_날짜_랜덤” 형태로 정하는 방안
- 문서에 예시로 들어두면 협업 시 편리

비동기 구조 필요

Stable Diffusion이나 기타 생성 모델은 1회 추론 시 수 초 ~ 수십 초 이상의 시간이 걸릴 수 있다.
- 이때 클라이언트는 응답을 기다리는 동안 타임아웃 발생 또는 UX 저사 문제가 발생한다.

Polling 방식(클라이언트 주기적 확인)

예시 코드

sequenceDiagram
    participant Client
    participant API Server
    participant Worker (GPU 서버)
    participant S3

    Client->>API Server: POST /generate
    API Server->>Worker: 작업 큐에 등록
    API Server-->>Client: {"task_id": "xyz123"}

    loop 주기적 polling
        Client->>API Server: GET /result/xyz123
        API Server->>Worker: 상태 확인
        alt 작업 완료됨
            API Server-->>Client: {"status": "done", "image_url": "..."}
        else 진행중
            API Server-->>Client: {"status": "processing"}
        end
    end

API 예시

/generate - POST

{
  "prompt": "minimal wooden desk setup",
  "negative_prompt": "people, cartoon, blurry"
}

응답

{
  "task_id": "xyz123",
  "status": "queued"
}

/result/{task_id} - GET

{
  "status": "processing"
}

작업이 완료되면 예시코드

{
  "status": "done",
  "initial_image_url": "https://bucket.s3.amazonaws.com/images/12.png",
  "processed_image_url": "https://bucket.s3.amazonaws.com/images/123.png",
  "마우스": [
      {
      "title": "shopping mall title",
      "price": "21990원",
      "mall": "네이버",
      "category3": "마우스",
      "category4": "유선마우스",
      "link": "https://search.shopping.naver.com/catalog/...",
      "image": "https://... .jpg"
      },
      {
      ...
      },
      {
      ...
      }
  ],
  "item 2": [
      {
      "title": "shopping mall item title",
      "price": "N원",
      "mall": "mall name",
      "category3": "하위 카테고리2",
      "category4": "하위 카테고리1",
      "link": "shopping mall link",
      "image": "item image url"
      },
      {
      ...
      },
      {
      ...
      }
  ],
  ...
}

장단점

장점	단점
구현이 단순함	클라이언트가 계속 확인해야 하므로 비효율 발생 가능
서버 부하 조절 쉬움	실시간 알림이 없음 (실시간성 낮음)
대부분의 플랫폼과 호환	polling 간격이 짧으면 DDoS처럼 될 수 있다.

Webhook 방식 (서버가 클라이언트에게 결과 전송)

예시 코드

sequenceDiagram
    participant Client
    participant API Server
    participant Worker
    participant S3

    Client->>API Server: POST /generate (with webhook_url)
    API Server->>Worker: 작업 큐 등록
    API Server-->>Client: {"task_id": "xyz123"}

    Worker->>S3: 업로드
    Worker->>Client.webhook_url: POST {task_id, image_url}

API 예시

/generate - POST

{
  "prompt": "dark-themed desk with LED strip",
  "webhook_url": "https://myapp.com/notify"
}

응답

{
  "task_id": "xyz123",
  "status": "queued"
}

webhook_url로 POST되는 JSON

{
  "status": "done",
  "initial_image_url": "https://bucket.s3.amazonaws.com/images/12.png",
  "processed_image_url": "https://bucket.s3.amazonaws.com/images/123.png",
  "마우스": [
      {
      "title": "shopping mall title",
      "price": "21990원",
      "mall": "네이버",
      "category3": "마우스",
      "category4": "유선마우스",
      "link": "https://search.shopping.naver.com/catalog/...",
      "image": "https://... .jpg"
      },
      {
      ...
      },
      {
      ...
      }
  ],
  "item 2": [
      {
      "title": "shopping mall item title",
      "price": "N원",
      "mall": "mall name",
      "category3": "하위 카테고리2",
      "category4": "하위 카테고리1",
      "link": "shopping mall link",
      "image": "item image url"
      },
      {
      ...
      },
      {
      ...
      }
  ],
  ...
}

장단점

장점	단점
클라이언트가 기다릴 필요 없음	외부 서버가 webhook을 받도록 구성되어 있어야 함
사용자에게 알림 기반 UX 구현 가능	보안 이슈 (서명/인증 필요)
빠른 반응성, 실시간 알림 가능	Webhook 실패 시 retry 정책 필요

결론

프론트엔드 웹/앱에서 주기적으로 확인 가능한 Polling 방식을 사용할 예정
사내 연동, 백엔드 -> 백엔드 고성능 서버 통신이 필요하면 Webhook
- 초기 MVP, 구조 단순 -> Polling으로 시작하고 Webhook 확장 고려

AI_API명세 backup - 100-hours-a-week/16-Hot6-wiki GitHub Wiki

API의 엔드포인트 목록과 기능 설명

흐름도

`generate` 입⋅출력 명세

1. initial_image_url

2. prompt

3. negative Prompt

4. num_inference_steps

5. guidance_scale

6. height, width

FastAPI 설계 예시

`/generate` 응답 예시

1. initial_image_url

2. processed_image_url

3. Item_i

오류 처리 방안 및 예외 사항

400(Bad Request))

422(Unprocessable Entity))

500(Internal Server Error)

API 버전 관리(Versioning)

고려사항

⚠️ GitHub.com Fallback ⚠️

AI_API명세 backup - 100-hours-a-week/16-Hot6-wiki GitHub Wiki

API의 엔드포인트 목록과 기능 설명

흐름도

generate 입⋅출력 명세

1. initial_image_url

2. prompt

3. negative Prompt

4. num_inference_steps

5. guidance_scale

6. height, width

FastAPI 설계 예시

/generate 응답 예시

1. initial_image_url

2. processed_image_url

3. Item_i

오류 처리 방안 및 예외 사항

400(Bad Request))

422(Unprocessable Entity))

500(Internal Server Error)

API 버전 관리(Versioning)

고려사항

⚠️ **GitHub.com Fallback** ⚠️

`generate` 입⋅출력 명세

`/generate` 응답 예시

⚠️ GitHub.com Fallback ⚠️