비디오 인코딩 (Burn) API

전문적인 스타일이 적용된 하드코딩 비디오 생성을 위해 고성능 렌더링 클러스터에 프로젝트를 제출합니다.

POST/api/v1/burn

빠른 구현

curl -X POST https://api.srtgen.com/api/v1/burn \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "proj_8k2n9m1b",
  "resolution": "1080p"
}'

POSThttps://api.srtgen.com/api/v1/burn

파라미터

파라미터	유형	필수 여부	설명
핵심 파라미터
`projectId`	String	Yes	비디오와 자막이 포함된 프로젝트의 고유 식별자입니다.
`resolution`	String	No	원하는 출력 비디오 해상도. 옵션: original, 1080p, 720p, 480p \| 기본값 (Default): 원본 (original)
`fileName`	String	No	생성된 MP4 파일의 커스텀 이름.
`language`	String	No	인코딩될 자막의 대상 언어. 기본값 (Default): 원본 (original)
다국어 지원 (이중 자막)
`languages`	Array	No	한 비디오에 여러 자막 트랙을 표시하기 위한 구성. 제한: 최대 3개 언어
-`language`	String	Yes*	해당 언어 슬롯의 코드 (예: 'zh' 또는 'original').
-`lineBreakRules`	Object	No	언어별 세분화 오버라이드.
-`styleSettings`	Object	No	언어별 스타일링 (이중 자막 위치 지정에 중요).
줄바꿈 규칙 (lineBreakRules)
`lineBreakRules`	Object	No	자막 세분화 로직을 위한 중첩 객체.
-`maxChars`	Number	No	줄당 허용되는 최대 글자 수. 범위: 5 - 100 \| 기본값 (Default): 45
-`maxWords`	Number	No	자막 줄당 허용되는 최대 단어 수. 범위: 1 - 20 \| 기본값 (Default): 10
-`balanceLines`	Boolean	No	여러 줄 자막에서 줄 길이를 균등하게 맞춤. 기본값 (Default): true
-`sentenceSplit`	Boolean	No	문장이 끝나는 지점에서 줄바꿈 선호. 기본값 (Default): true
-`gapThreshold`	Number	No	한 줄 내 단어 간 최대 간격(초). 범위: 0.1 - 2.0 \| 기본값 (Default): 0.4
기본 스타일 (styleSettings)
`uppercase`	Boolean	No	모든 텍스트를 대문자로 강제 변환.
`styleSettings`	Object	No	시각적 스타일 오버라이드를 위한 중첩 객체.
-`preset`	String	No	기본값으로 내장 스타일 프리셋 적용. 옵션: standard-stream, classic-apple, etc.
-`fontSize`	Number	No	비디오 높이 대비 글꼴 크기 비율. 기본값 (Default): 0.045
-`fontFamily`	String	No	렌더링에 사용되는 표준 글꼴 이름. 기본값 (Default): Arial
-`bold`	Boolean	No	텍스트에 굵게 스타일 적용. 기본값 (Default): false
-`italic`	Boolean	No	텍스트에 기울임꼴 스타일 적용. 기본값 (Default): false
색상 및 테두리
-`primaryColor`	Hex	No	기본 텍스트 색상 16진수 코드. 기본값 (Default): #FFFFFF
-`secondaryColor`	Hex	No	보조 색상 (가라오케 효과 등에 사용). 기본값 (Default): #00FFFF
-`outlineColor`	Hex	No	텍스트 외곽선 색상. 기본값 (Default): #000000
-`outline`	Number	No	외곽선 두께 (높이 대비 비율). 기본값 (Default): 0.002
-`shadow`	Number	No	그림자 깊이 (높이 대비 비율). 기본값 (Default): 0.001
위치 지정 (비율 0-1)
-`alignment`	Number	No	ASS 정렬 코드 (1-9). 하단 중앙은 2입니다. 범위: 1 - 9 \| 기본값 (Default): 2
-`posX`	Number	No	가로 위치 (0 = 왼쪽, 1 = 오른쪽). 기본값 (Default): 0.5
-`posY`	Number	No	세로 위치 비율 (0 = 상단, 1 = 하단). 기본값: 0.88.
-`marginV`	Number	No	상/하단으로부터의 세로 여백 비율. 기본값: 0.056.
애니메이션 및 효과
-`fadeIn`	Number	No	페이드 인 지속 시간(밀리초).
-`fadeOut`	Number	No	페이드 아웃 지속 시간(밀리초).
-`karaoke`	String	No	가라오케 태그 유형 (k, kf, ko, ks).

예시: 표준 스트림 스타일

curl -X POST https://api.srtgen.com/api/v1/burn \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "proj_8k2n9m1b",
  "resolution": "1080p",
  "styleSettings": {
    "preset": "standard-stream",
    "fontSize": 0.055,
    "bold": true
  }
}'

POSThttps://api.srtgen.com/api/v1/burn

고급: 이중 언어 인코딩

curl -X POST https://api.srtgen.com/api/v1/burn \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "projectId": "proj_8k2n9m1b",
  "languages": [
    {
      "language": "original",
      "styleSettings": {
        "preset": "classic-apple",
        "posY": 0.85
      }
    },
    {
      "language": "es",
      "styleSettings": {
        "preset": "classic-apple",
        "posY": 0.75,
        "primaryColor": "#FFFF00"
      }
    }
  ]
}'

POSThttps://api.srtgen.com/api/v1/burn

상태 및 응답

1. 비동기 초기화

클라우드 인코딩 작업은 비동기식입니다. 렌더링 클러스터가 작업을 수락하면 API는 즉시 burnId를 반환합니다.

내보내기 상태 엔드포인트를 사용하여 진행 상황과 최종 비디오 URL을 확인하세요.

응답: 200 OK

{
  "success": true,
  "burnId": "brnc_abc123",
  "status": "running"
}

2. 추적 및 가져오기

최종 결과를 얻으려면 초기화 시 받은 burnId를 사용하여 프로젝트 상태를 폴링하세요.

curl -X POST https://api.srtgen.com/api/v1/export/proj_xxx \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "output": "mp4",
  "burnId": "brnc_abc123"
}'

POSThttps://api.srtgen.com/api/v1/export/proj_xxx

완료되면 상태가 completed로 변경되고 resultUrl(다운로드 가능한 비디오)이 제공됩니다.

내보내기 엔드포인트를 통한 추적

{
  "status": "completed",
  "resultUrl": "https://cdn.b2.com/video.mp4"
}

오류 코드

상태	오류 코드	설명
400	missing_parameter	projectId가 필수입니다.
400	missing_video	프로젝트에 연결된 소스 비디오가 없습니다.
401	unauthorized	API 키가 누락되었거나 유효하지 않습니다.
403	insufficient_balance	비디오 길이에 비해 크레딧이 부족합니다.
404	not_found	프로젝트 ID가 존재하지 않습니다.
500	burn_submission_failed	렌더링 클러스터가 가득 찼거나 연결할 수 없습니다.
500	export_error	자막 처리 중 오류가 발생했습니다.
500	server_error	예기치 않은 내부 서버 오류가 발생했습니다.

이 페이지가 도움이 되었나요?