From cloudflare-stream
Cloudflare Stream 동영상 업로드 및 스트리밍 서비스 구축. FastAPI 서버로 동영상을 Cloudflare Stream에 업로드하고 HLS 스트리밍 URL을 반환하는 REST API 서버 생성. 동영상 업로드(파일/URL), 상태 확인, 목록 조회, 삭제 기능 포함. Cloudflare Stream API 연동, multipart/form-data 업로드, direct_upload URL 방식 사용. 키워드: cloudflare, stream, video upload, 동영상 업로드, 스트리밍, HLS, FastAPI, 영상 서비스.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cloudflare-stream:cloudflare-streamThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Cloudflare Stream을 이용한 동영상 업로드 및 HLS 스트리밍 FastAPI 서버를 구축합니다.
Cloudflare Stream을 이용한 동영상 업로드 및 HLS 스트리밍 FastAPI 서버를 구축합니다.
이 스킬이 호출되면 다음 단계를 자동으로 수행합니다:
.env 파일을 읽어서 다음 변수 확인:
CLOUDFLARE_ACCOUNT_IDCLOUDFLARE_API_TOKEN없으면 .env 파일 생성 안내:
CLOUDFLARE_ACCOUNT_ID=your_account_id_here
CLOUDFLARE_API_TOKEN=your_api_token_here
Cloudflare 정보 확인 방법:
Stream:Edit 권한 필요requirements.txt 또는 pyproject.toml 확인 후 패키지 설치:
pip install fastapi uvicorn httpx python-dotenv python-multipart
scripts/main.py를 프로젝트에 복사하거나, 기존 서버가 있으면 아래 엔드포인트 패턴을 참고하여 통합합니다.
uvicorn main:app --reload --port 8000
사용자에게 다음 정보 제공:
POST /upload/file — 로컬 파일 업로드POST /upload/url — 외부 URL 업로드GET /status/{video_id} — 처리 상태 확인GET /videos — 전체 목록 조회DELETE /video/{video_id} — 동영상 삭제프로젝트/
├── main.py # FastAPI 서버 (scripts/main.py 참조)
├── .env # Cloudflare 인증 정보
└── requirements.txt
Cloudflare direct_upload URL을 발급받아 multipart/form-data로 전송합니다.
# 업로드 흐름
# 1. POST /stream/direct_upload → 서명된 uploadURL + video_id 발급
# 2. 발급된 uploadURL로 multipart/form-data POST 전송
# 3. video_id로 스트리밍 URL 구성하여 반환
핵심: raw bytes 전송 (
Content-Type: video/mp4) 시 Cloudflare에서Decoding Error발생. 반드시files={"file": (filename, content, "video/mp4")}사용.
curl -X POST http://localhost:8000/upload/file \
-F "[email protected]"
curl -X POST http://localhost:8000/upload/url \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/video.mp4", "name": "My Video"}'
| status 값 | 의미 |
|---|---|
pending | 처리 대기 중 |
inprogress | 인코딩 중 |
ready | 스트리밍 준비 완료 |
error | 처리 실패 |
업로드 직후에는 pending 상태이며, 처리 완료 후 ready가 됩니다.
HLS: https://{ACCOUNT_ID}.cloudflarestream.com/{VIDEO_ID}/manifest/video.m3u8
썸네일: https://{ACCOUNT_ID}.cloudflarestream.com/{VIDEO_ID}/thumbnails/thumbnail.jpg
file_content = await file.read()
async with httpx.AsyncClient(timeout=600) as client:
upload_response = await client.post(
upload_url,
files={"file": (file.filename, file_content, "video/mp4")},
)
def build_streaming_urls(video_id: str) -> tuple[str, str]:
subdomain = f"{CLOUDFLARE_ACCOUNT_ID}.cloudflarestream.com"
streaming_url = f"https://{subdomain}/{video_id}/manifest/video.m3u8"
thumbnail_url = f"https://{subdomain}/{video_id}/thumbnails/thumbnail.jpg"
return streaming_url, thumbnail_url
| 오류 | 원인 | 해결 |
|---|---|---|
Decoding Error | raw bytes 업로드 | multipart/form-data 사용 |
401 Unauthorized | API 토큰 오류 | Stream:Edit 권한 확인 |
404 Not Found | 잘못된 video_id | video_id 재확인 |
credentials not configured | .env 없음 | .env 파일 생성 |
references/api-guide.mdscripts/main.pyCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub auraworks/my-marketplace --plugin cloudflare-stream