github/transloadit-media-processing

transloadit-media-processing은(는) 무엇을 하나요?

Transloadit을 사용하여 미디어 파일(비디오, 오디오, 이미지, 문서)을 처리합니다. 비디오를 HLS/MP4로 인코딩하거나, 썸네일을 생성하거나, 이미지 크기를 조절하거나 워터마크를 추가하거나, 오디오를 추출하거나, 클립을 연결하거나, 자막을 추가하거나, 문서 OCR을 수행하거나, 대규모 미디어 처리 파이프라인을 실행해야 할 때 사용하세요. 86개 이상의 처리 로봇을 통해 파일 변환을 지원합니다.

개요

github/transloadit-media-processing 스킬을 사용하면 Transloadit API를 통해 미디어 파일을 손쉽게 처리할 수 있습니다. 템플릿 ID나 인라인 파이프라인 정의를 사용하여 Assembly을 생성하고, 파일 업로드와 변환을 시작하며, 처리 결과를 받아볼 수 있습니다.

주요 개념

• Assembly: Transloadit의 미디어 처리 작업 단위입니다. 하나 이상의 파일을 업로드하고 변환 파이프라인(로봇 체인)을 실행합니다.
• 로봇(Robots): 미디어 처리 단계를 나타냅니다 (예: /video/encode, /image/resize, /document/ocr).
• 템플릿(Template): 재사용 가능한 Assembly 파이프라인 정의입니다.
• 알림(Notification): Assembly가 완료되면 HTTP POST로 결과를 전송하는 웹훅입니다.

빠른 시작

기본 사용법

import requests
import json

# Assembly 생성
assembly = {
    "steps": {
        ":original": {
            "robot": "/upload/handle"
        },
        "thumbnails": {
            "use": ":original",
            "robot": "/video/thumbnails",
            "count": 3
        }
    }
}

response = requests.post(
    "https://api2.transloadit.com/assemblies",
    data={
        "params": json.dumps(assembly)
    },
    files={"file": open("video.mp4", "rb")},
    auth=("YOUR_TRANSLOADIT_KEY", "")
)

result = response.json()
print(f"Assembly URL: {result['assembly_url']}")

처리 결과 확인

Assembly가 비동기적으로 처리되므로, 완료를 확인하기 위해 폴링하거나 알림을 설정할 수 있습니다:

import time

assembly_url = result["assembly_url"]
while True:
    status = requests.get(assembly_url).json()
    if status["ok"] == "ASSEMBLY_COMPLETED":
        print("처리 완료!")
        print(f"결과: {json.dumps(status['results'], indent=2)}")
        break
    elif status["ok"] == "ASSEMBLY_FAILED":
        print(f"처리 실패: {status['error']}")
        break
    time.sleep(2)

인증

Transloadit API 키와 시크릿이 필요합니다. 다음 환경 변수로 설정할 수 있습니다:

export TRANSLOADIT_KEY="your_key_here"
export TRANSLOADIT_SECRET="your_secret_here"

지원하는 로봇 (일부)

로봇 이름	설명
/video/encode	다양한 포맷(HLS, MP4, WebM 등)으로 비디오 인코딩
/video/thumbnails	비디오에서 썸네일 생성
/video/concat	여러 비디오 클립 연결
/video/merge	비디오와 오디오 트랙 병합
/image/resize	이미지 크기 조절
/image/watermark	이미지에 워터마크 추가
/audio/encode	오디오 포맷 변환
/document/ocr	문서에서 텍스트 추출

전체 목록은 Transloadit 로봇 문서를 참조하세요.

고급 사용법

템플릿 사용

템플릿 ID를 사용하여 사전 정의된 파이프라인을 실행할 수 있습니다:

response = requests.post(
    "https://api2.transloadit.com/assemblies",
    data={
        "template_id": "YOUR_TEMPLATE_ID"
    },
    files={"file": open("video.mp4", "rb")},
    auth=("YOUR_TRANSLOADIT_KEY", "")
)

알림 설정

assembly = {
    "steps": { ... },
    "notify_url": "https://your-server.com/transloadit-callback"
}

Assembly URL 캐싱

Transloadit은 Assembly URL에 대해 강력한 CDN 캐싱을 제공합니다. 동일한 URL을 재요청하면 캐시된 결과를 반환하여 성능을 향상시킵니다.

오류 처리

오류 응답은 일반적으로 다음과 같은 구조를 가집니다:

{
    "ok": "REQUEST_ERROR",
    "error": "DESCRIPTION",
    "http_code": 400
}

일반적인 오류 코드:

• 400: 잘못된 요청 (매개변수 누락 등)
• 401: 인증 오류
• 403: 권한 없음 (할당량 초과 등)
• 429: 요청 과다 (속도 제한)
• 500: 내부 서버 오류

추가 리소스

• Transloadit API 문서
• Transloadit 대시보드 (계정 생성 및 키 관리)
• 로봇 참조