구현하게된 이유

Tencent Cloud WAND의 AIGC API는 텍스트(LLM Chat), 이미지 생성, 영상 생성까지 폭넓은 모달리티를 지원합니다. 문제는 이 API들을 팀에서 평가하거나 데모로 보여줄 때였습니다. 매번 curl을 치거나 Postman 컬렉션을 돌려야 했고, 다음 세 가지가 특히 불편했습니다.

• 키 관리가 번거롭다. Tencent SecretKey와 AIGC API Token을 개발자마다 로컬에 들고 있다 보니, 누가 어떤 키로 얼마나 호출했는지 파악할 방법이 없었습니다.
• 멀티모달 테스트가 파편화돼 있다. 텍스트는 OpenAI-compatible endpoint, 이미지·영상은 MPS API로 인증 방식까지 달라서, 하나로 묶어 비교할 도구가 없었습니다.
• 비용 감이 안 잡힌다. 어떤 모델에, 어떤 사용자가, 얼마나 토큰을 소비했는지 한눈에 보고 싶었습니다.

그래서 브라우저 하나로 LLM Chat · 이미지 생성 · 영상 생성을 모두 테스트하고, 토큰별 사용량까지 자동으로 기록하는 AIGC Playground를 만들었습니다.

전체 아키텍처

┌──────────────────────────────────────────────────────────────┐
│                    Browser (Static Frontend)                 │
│  ┌──────────┐  ┌───────────────┐  ┌───────────────────────┐ │
│  │ LLM Chat │  │ Image Gen     │  │ Video Gen             │ │
│  └────┬─────┘  └──────┬────────┘  └──────────┬────────────┘ │
│       └───────────────┼──────────────────────┘              │
│                       │ /api/*                              │
└───────────────────────┼─────────────────────────────────────┘
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                   FastAPI Backend (app.py)                   │
│  ┌─────────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │ Token Admin     │  │ Usage Stats  │  │ COS Bucket     │  │
│  │ CRUD + Registry │  │ SQLite       │  │ Selection      │  │
│  └────────┬────────┘  └──────┬───────┘  └───────┬────────┘  │
└───────────┼──────────────────┼───────────────────┼───────────┘
            ▼                  ▼                   ▼
┌────────────────┐  ┌──────────────┐  ┌──────────────────────┐
│ Tencent VOD    │  │ Tencent MPS  │  │ Tencent COS          │
│ AIGC Token API │  │ Image/Video  │  │ Output Storage       │
│ Text AIGC EP   │  │ Task API     │  │                      │
└────────────────┘  └──────────────┘  └──────────────────────┘

브라우저 정적 프론트 → FastAPI 백엔드(3개 모듈) → Tencent VOD · MPS · COS

구조를 풀어 설명하면 이렇습니다. 브라우저에 올라가는 정적 프론트엔드는 LLM Chat · Image Gen · Video Gen 세 개의 UI를 담고 있고, 모든 요청을 /api/* 경로 하나로 보냅니다. 이 요청은 FastAPI 백엔드가 받아 세 갈래로 처리합니다. Token Admin은 토큰 생성·조회·삭제와 로컬 레지스트리를 담당하고, Usage Stats는 모든 호출을 SQLite에 기록하며, COS Bucket 모듈은 결과물 저장 버킷을 관리합니다. 백엔드는 다시 Tencent의 세 서비스(토큰 API·텍스트 endpoint를 담당하는 VOD, 이미지·영상 태스크 API인 MPS, 결과물 저장소 COS)로 연결됩니다.

설계할 때 잡은 원칙은 세 가지입니다.

1 키를 노출하지 않는다 모든 Tencent API 호출은 백엔드를 경유하며, 브라우저에는 SecretKey도 Token도 내려가지 않습니다.

2 100% 정적 배포 public/를 그대로 S3(또는 COS)에 올리고 /api/*만 프록시. EdgeOne+COS면 CDN도 간단합니다.

3 호출마다 기록한다 누가·어떤 모델로·얼마나 썼는지 SQLite 하나로 가볍게, 대신 빠짐없이 남깁니다.

멀티모달 AIGC 통합: 하나의 UI, 세 가지 모달리티

LLM Chat — OpenAI & Claude Compatible

Tencent Cloud WAND의 텍스트 AIGC는 두 가지 호환 endpoint를 제공합니다.

Endpoint	호환 형식	용도
/v1/chat/completions	OpenAI-compatible	GPT 계열 모델 호출
/v1/messages	Claude-compatible	Claude 계열 모델 호출

백엔드의 /api/chat/completions가 프론트에서 선택한 모델 타입에 따라 적절한 Tencent endpoint로 라우팅합니다. 사용자는 모델만 고르면 됩니다.

Image Generation — 비동기 태스크 패턴

이미지 생성은 Tencent MPS의 CreateAigcImageTask → DescribeAigcImageTask 흐름을 따릅니다. 요청을 보내면 TaskId가 반환되고, 폴링으로 결과를 확인하는 비동기 패턴입니다. 프론트가 이 폴링을 자동 처리하므로 사용자는 프롬프트만 입력하고 결과 이미지를 기다리면 됩니다.

Video Generation — 동일한 비동기 패턴

영상 생성도 CreateAigcVideoTask → DescribeAigcVideoTask로 같은 패턴입니다. 이미지 생성보다 시간이 더 걸리지만 UI 흐름은 동일하게 유지했습니다.

COS Storage 연동

생성 결과물을 Tencent COS Bucket에 저장하는 옵션도 넣었습니다. 요청에 StoreCosParam을 포함하면 결과물이 지정된 버킷 경로(/aigc-output/images/ 또는 /aigc-output/videos/)에 자동 저장됩니다. 선택하지 않으면 광저우 리전 임시 스토리지에 보관되는데, 데모 용도라면 그것으로 충분합니다.

토큰 관리와 사용량 추적

★ 이 프로젝트에서 가장 공을 들인 부분이 토큰별 사용량 추적입니다.

Token Admin

Tencent의 AIGC API Token 관리 API(CreateAigcApiToken, DescribeAigcApiTokens, DeleteAigcApiToken)를 래핑해, UI에서 토큰을 생성·조회·삭제할 수 있게 했습니다.

한 가지 아쉬운 점은 Tencent의 토큰 목록 API가 username 필드를 반환하지 않는다는 것입니다. 그래서 로컬에 aigc_token_registry.json을 두고 username ↔ api_token 매핑을 직접 관리했습니다. 토큰 생성 시 username을 입력받아 레지스트리에 기록해두고, 이후 사용량 기록을 해당 username으로 귀속시킵니다.

Usage Stats — SQLite 기반 경량 추적

모든 API 호출 결과를 aigc_usage.sqlite3에 기록합니다. 저장 항목은 다음과 같습니다.

• username — 어떤 사용자의 호출인지
• token preview — 어떤 토큰으로 호출했는지 (전체 토큰은 저장하지 않음)
• modality — llm, image, video 중 어느 모달리티인지
• model — 어떤 모델을 사용했는지
• success / status code — 성공 여부
• latency — 응답 시간
• token usage — LLM의 경우 input/output 토큰 수
• timestamp — 호출 시각

이 데이터를 바탕으로 /api/usage/summary는 사용자별·모달리티별 요약을, /api/usage/events는 개별 호출 이력을 제공합니다.

LLM Chat의 토큰 사용량은 LiteLLM으로 파싱합니다. LiteLLM이 OpenAI-compatible 응답에서 prompt_tokens, completion_tokens 등을 추출해주기 때문에, 이 값을 SQLite에 기록하면 어떤 사용자가 어떤 모델로 하루에 몇 토큰을 썼는지 바로 확인할 수 있습니다.

보안 설계: 프론트엔드에 키를 노출하지 않기

데모용 도구라도 키 관리에서는 신중하게 처리했습니다.

! 문제. Tencent API를 호출하려면 SecretId/SecretKey(TC3 인증)와 AIGC API Token(Bearer 인증)이 필요합니다. 이걸 프론트에서 직접 쓰면 브라우저 DevTools만 열어도 키가 노출됩니다.

해결. 모든 Tencent API 호출을 FastAPI 백엔드를 통해 프록시하는 구조로 잡았습니다.

• LLM Chat — 프론트에서 /api/chat/completions를 호출하면, 백엔드가 Active User Token을 Bearer로 달아 Tencent text-aigc endpoint에 전달합니다.
• Image/Video 생성 — MPS API는 TC3 서명 인증을 쓰는데, 서명 생성은 전부 백엔드에서 처리합니다.
• COS Bucket 조회 — COS API 호출에 필요한 서명도 백엔드가 생성합니다.

결과적으로 프론트는 순수하게 /api/*만 호출하고, 실제 Tencent 인증 정보는 서버의 .env에만 존재합니다.

배포 구조

프론트와 백엔드를 분리 배포할 수 있도록 설계했습니다.

https://demo.example.com/          →  EdgeOne / COS (정적 프론트)
https://demo.example.com/api/*     →  FastAPI backend origin

정적 프론트. public/ 디렉토리의 index.html, app.js, styles.css를 그대로 COS에 올리면 됩니다. CDN(EdgeOne) 뒤에 두면 글로벌 서빙도 가능합니다.

백엔드. FastAPI 서버를 별도로 띄우고 /api/* 경로만 프록시하면 됩니다. uvicorn app:app --host 0.0.0.0 --port 8080으로 실행하면 끝입니다.

로컬 개발 시에는 FastAPI가 public/까지 서빙하기 때문에 http://127.0.0.1:8080 하나로 전부 동작합니다.

개발하면서 배운 것들

1. Tencent API TC3 서명의 통합 관리가 생각보다 까다롭다

AWS Signature V4와 비슷한 구조인데 세부 포맷이 미묘하게 다릅니다. 특히 X-TC-Action, X-TC-Timestamp 같은 커스텀 헤더를 정확히 맞춰야 하는데, 한 글자라도 틀리면 AuthFailure.SignatureFailure가 돌아옵니다. 디버깅이 힘들어 Debug View에 Request/Response를 누적으로 보여주는 기능을 넣었더니 서명 문제를 잡는 데 꽤 도움이 됐습니다.

2. 비동기 태스크의 폴링 UX

이미지·영상 생성은 비동기 태스크 방식이라 결과를 받으려면 DescribeAigcImageTask를 반복 호출해야 합니다. 처음에는 단순한 setInterval로 구현했지만, 태스크가 실패하거나 오래 걸리는 경우에 대한 처리가 필요했습니다. 최종적으로는 최대 폴링 횟수 제한 + 지수 백오프 + 상태 표시를 조합해 정리했습니다.

3. 토큰 레지스트리 관리 부분

Tencent API가 username을 반환하지 않는 이상 로컬 레지스트리에 의존할 수밖에 없습니다. 이 파일이 유실되면 토큰-사용자 매핑이 깨지는 문제가 있는데, 프로덕션이라면 DB에 넣겠지만 데모 도구의 범위에서는 JSON 파일로 충분하다고 판단했습니다.

정리하면…

이번에 구현한 프로젝트의 핵심적인 부분을 세 가지로 정리해봤습니다.

✓ 멀티모달 통합 텍스트·이미지·영상 생성을 하나의 UI에서 테스트·비교. 호출 방식은 달라도 UX는 통일했습니다.

✓ 사용량 가시성 누가·어떤 모델로·얼마나 썼는지 토큰 단위 추적. 비용 관리·패턴 분석의 기초 데이터가 됩니다.

✓ 보안과 편의의 균형 데모지만 키 노출은 원천 차단. 정적 프론트+API 백엔드 분리로 배포 유연성도 확보했습니다.

간단한 데모 프로젝트지만, PaaS 형식으로 제공되는 AIGC API 테스트를 하나로 모으고 사용량까지 한눈에 볼 수 있게 만들자는 목표로 완성했습니다. 고객에게 Tencent WAND AIGC 제품을 전달할 때 좋은 자료로 활용되었으면 하는 바램입니다. 감사합니다 😊

---

이 글에서 다루는 코드는 데모 목적으로 작성되었으며, 프로덕션 환경에서는 추가적인 인증·인가, 에러 핸들링, 스케일링 고려가 필요합니다.