API 및 연동

Genviso와 BetterToken으로 템플릿 기반 이미지 생성하기

시각 탐색과 백엔드 실행을 분리하고 좋은 프롬프트를 버전이 있는 프로덕션 템플릿으로 만드는 실전 가이드입니다.

BT

BetterToken

편집팀
8 분 분량

좋은 이미지 한 장이 만들어졌다고 해서 프로덕션 프로세스가 완성된 것은 아닙니다. 한 장이라면 프롬프트를 여러 번 고치고 결과를 비교한 뒤 직접 선택할 수 있습니다. 하지만 SKU가 수백 개라면 같은 방식은 비용이 큰 반복 실험이 됩니다. 조명, 카메라 각도, 소재를 바꿀 때마다 새 요청이 생기고, 무엇이 성공에 영향을 줬는지는 작성자의 기억에만 남습니다.

작업을 두 개의 순환으로 나누는 것이 좋습니다. 먼저 팀이 시각적 방향을 시험하고 재사용 가능한 규칙을 기록합니다. 다음으로 백엔드가 승인된 템플릿에 업무 데이터를 넣고 요청을 전송하며 결과 저장과 오류 처리를 맡습니다. 창의적인 탐색은 프로덕션 큐 밖에 남고, 구도를 고칠 때마다 서버 코드를 수정할 필요가 없어집니다.

코드에서 프롬프트를 조정하면 통제하기 어려운 이유

서로 연결된 변수가 너무 많다

이미지 모델은 피사체, 환경, 조명, 카메라 위치, 소재, 심도, 색상 팔레트에 동시에 반응합니다. 세럼 병 사진만 해도 다음 선택에 따라 결과가 크게 달라집니다.

  • 정면 구도와 45도 위쪽 구도
  • 강한 방향광과 부드러운 확산광
  • 반사가 뚜렷한 유리와 무광 표면
  • 트래버틴, 금속, 단색 종이 배경
  • 85mm 매크로 느낌과 광각 구도

여러 값을 함께 바꾸면 어떤 문구가 이미지를 개선했는지 알 수 없습니다. 하나씩 바꾸면 요청 횟수가 빠르게 늘어납니다. BetterToken을 사용하는 백엔드는 Image API로 템플릿을 실행할 수 있지만, 검증 전에 큐를 시작하면 확인되지 않은 시각 가설만 대량으로 복제하게 됩니다.

용도마다 시각 문법이 다르다

상품 카드에는 읽기 쉬운 윤곽, 통제된 반사, 레이아웃용 여백이 필요합니다. 3D 일러스트는 형태와 소재 조건이 다릅니다. 소셜 포스터는 정보 위계, 대비, 안전 영역이 중요합니다. 모든 용도를 한 프롬프트로 처리하면 서로 모순되는 형용사가 쌓이기 쉽습니다.

다음처럼 템플릿 계열을 나누는 편이 실용적입니다.

skincare_product
luxury_watch
food_photography
3d_illustration
social_poster

각 계열은 자체 필수 필드와 승인 기준을 정의합니다. 애플리케이션은 카테고리에 따라 템플릿을 선택하고 해당 상품이나 캠페인의 데이터를 채웁니다.

탐색과 프로덕션에는 다른 규칙이 필요하다

탐색 단계에서는 많은 변형과 주관적 비교가 가능합니다. 프로덕션에는 예측 가능한 계약, 템플릿 버전, 제한된 재시도, 작업 식별자, 명확한 승인 결과가 필요합니다.

코드에서 프롬프트 수정
→ API 요청 전송
→ 이미지 열기
→ 코드 다시 수정
→ 다음 요청 전송

이 과정에는 시각적 결정을 승인하는 지점이 없습니다. 따라서 디자인 논의가 매번 백엔드와 작업 큐까지 영향을 줍니다.

시각 가설에서 CMS 파일까지 이어지는 구조

시각 탐색 단계에서 팀은 Genviso의 시각 프롬프트 갤러리로 후보를 비교하고 구도, 조명, 스타일을 확인한 뒤 성공한 프롬프트 구조를 보관합니다. 서버 실행 단계에서는 애플리케이션이 BetterToken의 OpenAI 호환 Base URL과 사용자가 소유한 API Key를 사용해 데이터를 넣고 현재 이용 가능한 모델을 호출한 뒤 결과를 기록합니다. 두 단계 사이에서 전달되는 것은 선택된 이미지나 구두 지시가 아니라 버전이 지정된 Prompt Template입니다.

큐를 연결하기 전에 이 경계를 시험하려면 본인의 API Key를 생성하고 승인된 템플릿으로 확인 요청 한 번을 실행한 뒤 모델, 상태, 실제 차감을 Dashboard에서 즉시 대조하세요. 시각 탐색을 프로덕션 요청으로 바꾸지 않고 서버 경로만 검증할 수 있습니다.

시각 탐색
    ↓
Prompt Template 검증
    ↓
변수와 제약 확정
    ↓
PIM / CMS / SKU 데이터 삽입
    ↓
백엔드 Image API 요청
    ↓
파일, 상태, 메타데이터 저장
    ↓
시각 승인

각 전환점에는 검증할 수 있는 산출물이 있어야 합니다.

단계산출물다음 단계 조건
시각 탐색채택안과 제외안영향을 주는 변수를 이해함
템플릿 검증이름 있는 변수를 가진 프롬프트대표 상품 여러 개에서 동작함
통합렌더 함수와 입력 스키마API 요청 전에 필수 필드를 검사함
테스트저장 파일과 요청 기록파일이 열리고 모델과 상태가 맞음
프로덕션template_id, 버전, job_id가 있는 작업재시도가 제한되고 결과가 SKU와 연결됨

1단계: 시각 결정을 템플릿으로 만들기

화장품 스튜디오 촬영은 다음 구조에서 시작할 수 있습니다.

Commercial studio product photography of {subject}.

Environment:
{environment}

Visual style:
{visual_style}

Lighting:
{lighting}

Composition:
{composition}

Color palette:
{color_palette}

Crisp reflections, premium material texture,
high-end commercial editorial photography.

설명 순서와 시각 차원은 고정하고 subject, environment, visual_style, lighting, composition, color_palette 값만 서로 독립적으로 변경합니다.

개발자에게 넘기기 전에 네 가지를 더 정합니다.

  1. 필수 필드. subject나 composition이 없으면 요청을 보내지 않습니다.
  2. 허용 값. 승인된 각도가 세 가지라면 CMS 자유 입력보다 열거형이 낫습니다.
  3. 금지 조합. 투명 용기와 거울 배경은 별도 템플릿이 필요할 수 있습니다.
  4. 승인 기준. 상품 윤곽이 읽히고 로고가 변형되지 않으며 상품이 잘리지 않고 배경이 최종 레이아웃에 적합해야 합니다.

프롬프트 옆에는 기계가 읽을 수 있는 계약을 저장합니다.

{
  "template_id": "skincare_product_v3",
  "required_variables": [
    "subject",
    "environment",
    "visual_style",
    "lighting",
    "composition",
    "color_palette"
  ],
  "output_size": "1024x1024"
}

template_id의 버전은 재현성을 보장합니다. 디자이너가 조명이나 구도를 바꾸면 새 작업만 다음 버전을 사용하고, 기존 결과는 이전 버전과 계속 연결됩니다.

2단계: 템플릿을 백엔드에 연결하기

첫 테스트에는 공식 Python SDK인 openai, 본인의 BetterToken API Key, 현재 Image API 문서에서 확인한 Model ID가 필요합니다. 키와 모델은 환경 변수에 보관합니다.

python -m pip install openai

export BETTERTOKEN_API_KEY="your_api_key_here"
export BETTERTOKEN_IMAGE_MODEL="current_image_model_id"

실제 키를 저장소, 프롬프트, 화면 캡처, 로그에 넣지 마세요. 프로덕션에서는 비밀 관리 도구를 사용하고 애플리케이션이나 환경마다 키를 분리하세요.

아래 예제는 템플릿을 렌더링하고 요청 한 번을 보낸 뒤 b64_json에서 PNG를 저장합니다.

import base64
import os
from pathlib import Path
from typing import Mapping
from openai import OpenAI

client = OpenAI(
    base_url="https://www.bettertoken.ai/v1",
    api_key=os.environ["BETTERTOKEN_API_KEY"],
)

def render_product_prompt(variables: Mapping[str, str]) -> str:
    return f"""
Commercial studio product photography of {variables['subject']}.

Environment:
{variables['environment']}

Visual style:
{variables['visual_style']}

Lighting:
{variables['lighting']}

Composition:
{variables['composition']}

Color palette:
{variables['color_palette']}

Crisp reflections, premium material texture,
high-end commercial editorial photography.
""".strip()

product = {
    "subject": "frosted amber glass serum bottle with a minimalist gold dropper",
    "environment": "organic travertine pedestal surrounded by subtle water ripples",
    "visual_style": "high-end botanical skincare editorial",
    "lighting": "warm directional morning rim light with soft diffused fill",
    "composition": "centered 85mm macro product photography with shallow depth of field",
    "color_palette": "earthy amber, warm beige and subtle gold",
}

response = client.images.generate(
    model=os.environ["BETTERTOKEN_IMAGE_MODEL"],
    prompt=render_product_prompt(product),
    size="1024x1024",
    n=1,
)

image_base64 = response.data[0].b64_json
if not image_base64:
    raise RuntimeError("Image API response does not contain b64_json")

output_path = Path("serum-product.png")
output_path.write_bytes(base64.b64decode(image_base64))
print(f"Saved: {output_path}")

client.images.generate(...) 호출과 b64_json 디코딩은 현재 SDK 계약을 따릅니다. 모델을 BETTERTOKEN_IMAGE_MODEL에서 읽기 때문에 Prompt Template이나 업무 로직을 다시 작성하지 않고 변경할 수 있습니다.

최소 일괄 작업 루프

아래는 통합 계층을 명시한 의사 코드입니다. save_job, generate_image, ApiError는 저장소와 API 클라이언트 어댑터를 뜻하며 SDK의 추가 메서드가 아닙니다.

MAX_ATTEMPTS = 3
RETRYABLE_STATUS = {429, 500, 502, 503, 504}

for sku in sku_rows:
    variables = validate_variables(sku)  # API 호출 전
    prompt = render_product_prompt(variables)
    job_id = uuid4().hex
    prompt_hash = sha256(prompt.encode()).hexdigest()
    save_job(job_id=job_id, sku_id=sku["id"],
             template_id="skincare_product_v3",
             prompt_hash=prompt_hash, status="pending")

    for attempt in range(1, MAX_ATTEMPTS + 1):
        save_job(job_id=job_id, status="running", attempt=attempt)
        try:
            result = generate_image(prompt)
        except ApiError as error:
            if error.status_code in {400, 401}:
                save_job(job_id=job_id, status="failed", error_code=error.status_code)
                break
            if error.status_code not in RETRYABLE_STATUS or attempt == MAX_ATTEMPTS:
                save_job(job_id=job_id, status="failed", error_code=error.status_code)
                break
            sleep(min(2 ** attempt, 8))
            continue
        except TimeoutError:
            save_job(job_id=job_id, status="unknown", error_code="timeout")
            break  # 재전송 전에 Dashboard와 저장소 확인

        if not result.b64_json:
            save_job(job_id=job_id, status="failed", error_code="empty_output")
            break
        output_path = persist_png(job_id, result.b64_json)
        save_job(job_id=job_id, status="succeeded", output_path=output_path,
                 model=result.model, attempt=attempt)
        break

로컬 job_id는 SKU, 템플릿, 파일을 연결하지만 외부 요청을 멱등으로 만들지는 않습니다. 타임아웃 뒤에는 unknown 상태를 유지하고 Dashboard를 시간으로 검색한 뒤 저장소를 확인해서 한 번만 재전송할지 결정하세요.

문제 확인 순서

증상먼저 확인수정다시 검증
400필수 변수, 현재 Model ID, 지원되는 size데이터나 매개변수를 고치고 같은 요청을 자동 반복하지 않음확인 SKU 한 개를 실행하고 PNG 열기
401Key 변수 로드, 키 소유자, 프로토콜키를 로그에 남기지 않고 교체 또는 재생성최소 요청을 보내고 Dashboard에서 상태 찾기
429동시 실행 수와 작업 빈도새 작업 유입을 멈추고 동시성을 낮춰 제한된 backoff 적용요청 한 개를 통과시킨 뒤 부하를 천천히 복원
5xx요청 시간과 이미 한 시도 횟수MAX_ATTEMPTS까지만 반복하고 시간과 상태 저장템플릿을 바꾸지 않고 기다린 뒤 한 개 시험
타임아웃Dashboard와 저장소unknown을 유지하고 실패로 단정하지 않음기록과 파일이 없을 때 같은 로컬job_id로 한 번 재전송
빈 b64_json 또는 디코딩 실패현재 응답 형식, 모델, 매개변수Key 없이 오류를 저장하고 파싱이나 설정 수정SKU 한 개를 다시 실행해 PNG가 열리는지 확인

일괄 생성 전에 추가할 항목

요청 전에 데이터 검증하기

빈 material, product_name 안의 예상하지 못한 마크업, 승인된 팔레트 대신 들어온 자유 텍스트는 프롬프트를 바꿉니다. 필수 필드, 길이, 허용 값을 확인하고 최종 프롬프트 해시, template_id, SKU 식별자를 작업과 함께 저장하세요.

재시도 횟수 제한하기

타임아웃 뒤 재시도하면 애플리케이션이 첫 응답을 받지 못했더라도 이미지가 하나 더 생성될 수 있습니다. 최대 횟수와 대기 시간을 정하고 실행마다 job_id를 부여하세요. 400, 401, 모델 설정 오류를 무한 반복하지 말고 데이터, 키, 설정을 먼저 수정하세요.

기술 승인과 시각 승인 분리하기

HTTP 200과 유효한 PNG는 기술적 성공을 뜻합니다. 구도, 상품 변형, 브랜드 적합성은 별도로 평가합니다. 자동 작업은 파일과 메타데이터를 저장하고 다음 단계에서 템플릿의 시각 기준을 적용합니다.

사용 기록과 요청 대조하기

확인용 생성 뒤 시간으로 Dashboard 요청을 찾아 모델, 상태, 차감을 확인합니다. 제공되는 사용량 필드는 입력, 출력, 캐시 Token을 보여 줍니다. Dashboard는 사용량과 지출 메타데이터를 위한 곳이며 전체 프롬프트나 응답을 저장하는 곳이 아닙니다. 예산은 최신 모델 및 가격 페이지로 계산하고 실제 테스트 지출은 요청 기록에서 확인하세요.

상품 카탈로그 처리 예시

PIM / SKU 데이터베이스
↓
상품 카테고리 → template_id
↓
이름 / 소재 / 색상 / 배경
↓
필수 필드 검증
↓
Prompt Template 렌더링
↓
job_id가 있는 생성 작업
↓
Image API
↓
객체 스토리지
↓
시각 승인
↓
CMS / 미디어 라이브러리

프롬프트는 버전이 있는 프로덕션 객체가 됩니다. 어떤 템플릿이 파일을 만들었는지 추적하고, 버전별 제외 비율을 비교하며, 전체 통합을 다시 작성하지 않고 문제가 있는 변경을 되돌릴 수 있습니다.

시작 전 체크리스트

  • 대표 상품과 어려운 경계 사례로 템플릿을 시험했습니다.
  • template_id, 필수 변수, 승인 기준을 정의했습니다.
  • API Key가 소스 코드와 로그 밖에 있습니다.
  • Model ID를 환경 변수나 설정에서 읽습니다.
  • 테스트 요청 하나가 예상 크기의 유효한 파일을 만듭니다.
  • 400/401은 재시도 전에 데이터나 설정을 수정합니다.
  • 429/5xx 재시도 횟수가 제한되어 있습니다.
  • 각 작업이 SKU, job_id, 템플릿 버전, 저장 위치와 연결됩니다.
  • 기술 검증과 시각 승인을 분리했습니다.
  • 모델, 상태, 테스트 지출을 Dashboard에서 확인했습니다.

역할 분리가 협업을 단순하게 만드는 방법

Genviso는 대화형 순환을 담당합니다. 시각 방향을 빠르게 찾고 프롬프트를 비교하며 개발자에게 넘기기 전에 템플릿을 검증합니다. BetterToken은 서버 순환을 담당합니다. API Key, OpenAI 호환 연결, 현재 이용 가능한 모델 호출, 사용 기록을 처리합니다. 두 팀이 공유하는 계약은 변수, 버전, 승인 기준을 포함한 Prompt Template입니다.

승인된 템플릿을 실제 백엔드로 옮기고 대표 SKU 하나의 지출을 확인하려면 본인의 API Key를 생성하고 Image API 레퍼런스의 최소 요청을 실행한 다음, 큐를 연결하기 전에 Dashboard에서 모델, 상태, 차감을 확인하세요.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.