개발자 문서
API 한 번으로 파이프라인을 호출합니다.
아래는 주요 엔드포인트와 사용 흐름 요약입니다. OpenAPI 스펙 전문과 SDK, 온프레미스 운영 가이드는 계정 발급 후 접근할 수 있습니다.
# 1. 인코딩 Job 제출
curl -X POST https://api.lemonflex.net/v1/jobs \
-H "Authorization: Bearer $LEMONFLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": { "uri": "s3://my-bucket/source.mp4" },
"output": { "uri": "s3://my-bucket/out/" },
"profile": "hevc-4k-quality",
"enhance": { "superResolution": true, "denoise": "auto" }
}'
# => { "id": "job_7fK2xQ", "status": "queued" }
# 2. 상태 조회
curl https://api.lemonflex.net/v1/jobs/job_7fK2xQ \
-H "Authorization: Bearer $LEMONFLEX_API_KEY"인증
모든 요청은 HTTPS로 전송되며, API 키 또는 OAuth 2.0 액세스 토큰이 필요합니다.
API 키
서버 간 통신에 사용합니다. 키는 환경 변수로 관리하고 클라이언트 코드에 포함하지 마세요. 프로젝트 단위로 발급되며 권한 범위를 제한할 수 있습니다.
Authorization: Bearer lfx_live_a1b2c3d4e5f6...
Content-Type: application/jsonOAuth 2.0
사용자 위임이 필요한 경우 client credentials 플로우로 토큰을 발급받습니다. 토큰 유효 기간은 1시간이며 갱신이 필요합니다.
curl -X POST https://api.lemonflex.net/oauth/token \
-d grant_type=client_credentials \
-d client_id=$CLIENT_ID \
-d client_secret=$CLIENT_SECRET
# => { "access_token": "...", "expires_in": 3600 }주요 엔드포인트
배치 Job과 라이브 채널을 같은 리소스 모델로 다룹니다.
/v1/jobs인코딩 또는 Enhance Job을 제출합니다./v1/jobsJob 목록을 상태·기간으로 필터해 조회합니다./v1/jobs/{id}단일 Job의 상태, 진행률, 품질 지표를 조회합니다./v1/jobs/{id}대기 중이거나 진행 중인 Job을 취소합니다./v1/channels라이브 채널을 생성하고 입력 엔드포인트를 발급받습니다./v1/channels/{id}채널 상태와 실시간 지표를 조회합니다./v1/channels/{id}/start채널을 시작해 입력 수신과 송출을 개시합니다./v1/channels/{id}/stop채널을 정지합니다. 구성은 유지됩니다./v1/channels/{id}프로파일이나 ABR 래더를 변경합니다./v1/profiles사용 가능한 인코딩 프로파일 목록을 조회합니다./v1/profiles커스텀 프로파일을 등록합니다./v1/assets/{id}/metrics결과물의 VMAF · PSNR · 비트레이트 리포트를 조회합니다./v1/webhooks등록된 웹훅 엔드포인트를 조회합니다./v1/webhooks이벤트 수신 URL과 구독 이벤트를 등록합니다./v1/webhooks/{id}웹훅 등록을 해제합니다.사용 예시
가장 많이 쓰는 세 가지 흐름입니다.
Enhance 후 인코딩
저화질 소스를 복원한 뒤 같은 Job에서 인코딩까지 마칩니다.
{
"input": { "uri": "s3://src/old.mp4" },
"output": { "uri": "s3://dst/" },
"profile": "hevc-4k-quality",
"enhance": {
"superResolution": "4x",
"denoise": "auto",
"temporalStabilize": true
}
}라이브 채널 생성
SRT 입력을 받아 3단 ABR 래더로 송출합니다.
{
"name": "sports-ch-01",
"input": { "protocol": "srt", "mode": "listener" },
"profile": "hevc-4k-lowlatency",
"ladder": [
{ "height": 2160, "bitrate": 12000 },
{ "height": 1080, "bitrate": 5000 },
{ "height": 720, "bitrate": 2500 }
],
"packaging": ["ll-hls", "dash"]
}품질 리포트 조회
결과물의 VMAF와 비트레이트를 확인해 프로파일을 조정합니다.
from lemonflex import Client
client = Client(api_key=os.environ["LEMONFLEX_API_KEY"])
job = client.jobs.create(
input="s3://src/clip.mp4",
output="s3://dst/",
profile="av1-4k-efficient",
)
job.wait()
report = client.assets.metrics(job.asset_id)
print(report.vmaf, report.bitrate_kbps)인코딩 프로파일
프리셋을 그대로 쓰거나, 파라미터를 조합해 직접 정의할 수 있습니다.
| 프로파일 | 코덱 | 해상도 | 레이트 컨트롤 | 용도 |
|---|---|---|---|---|
h264-1080p-standard | H.264 | 1920×1080 | Capped VBR | 레거시 단말 호환 |
hevc-4k-quality | HEVC | 3840×2160 | VBR | VOD 카탈로그 기본 |
hevc-4k-lowlatency | HEVC | 3840×2160 | CBR | 라이브 송출 |
av1-4k-efficient | AV1 | 3840×2160 | VBR | 전송 비용 최소화 |
hevc-8k-archive | HEVC | 7680×4320 | CRF | 마스터 아카이브 |
웹훅과 오류 처리
Job 상태는 폴링 대신 웹훅으로 받는 것을 권장합니다.
웹훅 이벤트
job.completed- Job이 정상 완료되고 결과물이 출력 경로에 기록되었습니다.
job.failed- Job이 실패했습니다. 페이로드에 오류 코드와 원인이 포함됩니다.
channel.started- 라이브 채널이 입력을 수신하고 송출을 시작했습니다.
channel.degraded- 입력 손실이나 처리 지연으로 채널 품질이 저하되었습니다.
channel.stopped- 채널이 정지되었습니다. 의도적 정지와 장애를 페이로드로 구분합니다.
모든 웹훅 요청에는 X-Lemonflex-Signature 헤더가 포함됩니다. 수신 측에서 서명을 검증해 위조 요청을 차단하세요.
오류 코드
- 400
- 요청 본문이 스키마와 맞지 않습니다. 필드명과 타입을 확인하세요.
- 401
- API 키 또는 토큰이 없거나 유효하지 않습니다.
- 403
- 해당 리소스에 대한 권한이 없습니다. 키의 권한 범위를 확인하세요.
- 404
- 요청한 Job, 채널, 프로파일이 존재하지 않습니다.
- 409
- 현재 상태에서 수행할 수 없는 작업입니다. 예: 이미 정지된 채널 정지.
- 422
- 입력 소스를 읽을 수 없거나 지원하지 않는 포맷입니다.
- 429
- 요청 한도를 초과했습니다. Retry-After 헤더를 따르세요.
- 5xx
- 서버 측 오류입니다. 지수 백오프로 재시도하세요.
5xx 응답과 429는 지수 백오프로 재시도하세요. 4xx는 요청 자체를 수정해야 합니다.
클라이언트 라이브러리
직접 HTTP를 다루지 않고 언어별 SDK로 호출할 수 있습니다.
배치 파이프라인과 데이터 처리 스크립트에 적합합니다.
pip install lemonflex고동시성 서비스에서 채널을 제어할 때 사용합니다.
go get github.com/lemonflex/lemonflex-go백엔드 API와 서버리스 함수에서 호출합니다.
npm install @lemonflex/sdk개발자 자주 묻는 질문
REST와 gRPC 중 무엇을 써야 하나요?
배치 Job 제출과 상태 조회는 REST가 간편합니다. 라이브 채널의 실시간 지표를 스트리밍으로 받거나 호출 빈도가 높은 경우에는 gRPC가 유리합니다. 두 인터페이스가 같은 리소스 모델을 공유하므로 혼용해도 문제없습니다.
Job 상태를 폴링해도 되나요?
가능하지만 웹훅을 권장합니다. 폴링이 필요하다면 최소 5초 간격을 유지하세요. 더 짧은 간격은 429 응답을 받을 수 있습니다.
온프레미스에서도 같은 API를 쓰나요?
네. 엔드포인트 호스트만 사내 주소로 바뀌고 요청과 응답 스키마는 동일합니다. 클라우드에서 개발한 코드를 호스트 설정만 변경해 온프레미스에 사용할 수 있습니다.
요청 한도(rate limit)는 어떻게 되나요?
계정 등급에 따라 다릅니다. 응답 헤더의 X-RateLimit-Remaining과 X-RateLimit-Reset으로 현재 잔여량을 확인할 수 있습니다. 대량 배치가 필요하면 한도 상향을 요청해 주세요.
OpenAPI 스펙 파일을 받을 수 있나요?
네. OpenAPI 3.1 스펙과 gRPC Protobuf 정의를 계정 발급 시 함께 전달합니다. 코드 생성기로 클라이언트를 직접 만들어 쓰셔도 됩니다.