API Documentation

공용 갤러리 서버 연동 가이드 (V2.0)

파일 업로드 및 자동 썸네일

미디어 파일을 업로드합니다. 비디오의 경우 FFmpeg를 통해 자동으로 썸네일이 생성됩니다.

POST /api/upload

Parameters (Form-Data)

Key Type Description
file File 업로드할 미디어 파일 Required
media_type String video, image, other
title String 유튜브 및 갤러리 표시 제목
description String 영상 상세 설명
tags String 콤마(,)로 구분된 태그 목록
privacy String unlisted, private, public
meta_json String (JSON) 영상 제작 시 발생한 전체 메타데이터 (통째로 보관용)

Example (Python)

import requests
import json

url = "http://192.168.0.225:8080/api/upload"
video_file = "final_video.mp4"
json_file = "final_video.json"

# 전체 메타데이터 JSON 읽기
with open(json_file, "r", encoding="utf-8") as f:
    meta_raw = f.read()

with open(video_file, "rb") as f:
    files = {"file": f}
    data = {
        "media_type": "video",
        "title": "멋진 인공지능 영상",
        "description": "이 영상은 AI가 생성했습니다.",
        "meta_json": meta_raw,  # 원본 데이터 통째로 전송
        "privacy": "unlisted"
    }
    resp = requests.post(url, files=files, data=data)
    print(resp.json())

S3 이미 업로드된 미디어 등록 (DB 전용 등록)

미디어 파일 본체를 다시 업로드하지 않고, 이미 S3에 저장되어 있는 S3 오브젝트 키(s3_key)를 이용하여 메타데이터와 파일 정보만 데이터베이스에 직접 등록합니다. 비디오 형식의 경우, 썸네일 경로가 비어 있으면 FFmpeg가 S3에서 비디오를 읽어와 자동으로 썸네일을 생성 및 업로드해 줍니다.

POST /api/register

Parameters (JSON Body) application/json

Key Type Description
s3_key String S3 오브젝트 키 경로 (예: comment_shorts/695/video.mp4) Required
title String 유튜브 및 갤러리 표시 제목 (미지정 시 파일명)
description String 영상 상세 설명
tags String 콤마(,)로 구분된 태그 목록
media_type String video, image, audio, zip, other (미지정 시 확장자 기반 자동 매핑)
file_size Integer 파일 바이트 크기 (기본값: 0)
thumbnail_s3_key String 이미 생성되어 있는 S3 썸네일 키 (미지정 시 비디오 타입일 경우 자동 생성)
subtitle_text String 추출된 자막 텍스트
privacy String 공개범위 (unlisted, private, public)
yt_account String 유튜브 업로드용 계정 토큰명 (예: Default)

Example (Python)

import requests

url = "http://192.168.0.225:8080/api/register"
headers = {"Content-Type": "application/json"}

payload = {
    "s3_key": "comment_shorts/20260423_104828/comment_shorts_20260423_104828_ko_shorts.mp4",
    "title": "API 동기화 등록 영상",
    "description": "S3에 있는 원본 객체를 DB에 등록합니다.",
    "media_type": "video",
    "file_size": 23969091,
    "privacy": "unlisted"
}

resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

Example (urllib 기반 독립 실행 스크립트)

외부 서버에서 requests 같은 별도의 라이브러리 설치가 곤란한 환경에서도 파이썬 표준 라이브러리만을 활용해 원격으로 등록을 쏠 수 있는 전용 헬퍼 CLI 도구(register_media.py)를 제공합니다.

# 사용 예시 (터미널)
python3 register_media.py --url "http://192.168.0.225:8080" \
  --s3-key "comment_shorts/20260423_104828/comment_shorts_20260423_104828_ko_shorts.mp4" \
  --title "원격 등록 동영상" \
  --media-type "video" \
  --file-size 23969091

Example (Curl)

curl -X POST http://192.168.0.225:8080/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "s3_key": "comment_shorts/20260423_104828/comment_shorts_20260423_104828_ko_shorts.mp4",
    "title": "원격 Curl 등록",
    "media_type": "video"
  }'

메타데이터 수정

기존에 등록된 미디어의 정보를 수정합니다. 유튜브 배포 설정도 함께 업데이트됩니다.

PATCH /api/media/{id}

Parameters (Form-Data)

수정하고 싶은 필드만 포함하여 전송하면 됩니다.

Key Type Description
title String 새로운 제목
description String 새로운 설명
privacy String 배포 권한 변경
made_for_kids Boolean 아동용 여부

유튜브 배포 실행

저장된 메타데이터를 기반으로 유튜브 업로드를 시작합니다.

POST /api/media/{id}/publish

별도의 파라미터 없이 호출 시 DB에 저장된 최신 메타데이터를 사용하여 백그라운드 업로드가 시작됩니다.

목록 조회

등록된 모든 미디어 파일의 목록과 최신 Presigned URL을 가져옵니다.

GET /api/media