자막 번역을
워크플로에 연결하세요.

빠른 시작

키를 만든 후 Node.js 예제를 다운로드하세요. 비용 추정, 작업 제출, 상태 폴링, 번역된 SRT 저장까지 수행합니다. Node.js 20 이상이 필요하며 추가 패키지는 설치하지 않아도 됩니다.

export AST_BASE_URL='https://your-website-origin'
export AST_API_KEY='ast_YOUR_API_KEY'
node translate-subtitle.mjs input.srt zh plus translated.srt my-job-001
# 이중 언어 자막을 받으려면 마지막 인수에 true를 추가하세요:
node translate-subtitle.mjs input.srt zh plus bilingual.srt my-job-001 true

기본 URL을 이 사이트의 오리진으로 바꾸고, 다운로드한 스크립트를 SRT 파일과 같은 위치에 두세요. basic 또는 plus를 명시적으로 선택해야 합니다. 네트워크 오류 후 재시도할 때는 같은 작업 키, 입력, 옵션을 사용하세요. 같은 작업 키로 다시 다운로드하면 기존 번역을 재사용합니다. 출력 파일명은 아직 존재하지 않는 이름을 지정하세요.

인증

대시보드 → 보안 → API 키를 여세요. 키 이름을 지정하여 생성하세요. 같은 페이지에서 언제든지 전체 키를 다시 확인하고 복사하거나 키를 폐기할 수 있습니다.

Authorization: Bearer ast_YOUR_API_KEY

이 사이트의 오리진을 기본 URL로 사용하세요. 6개 엔드포인트 모두 유효한 키가 필요합니다. 계정당 활성 키를 5개까지 만들 수 있습니다. API 키는 해당 계정이 API로 만든 번역 작업과 크레딧 잔액에 접근할 수 있습니다.

본인 계정의 키를 사용하세요. 키를 비공개로 보관하고 배포하는 플러그인에 공용 키를 포함하지 마세요. 쿠키 인증이나 URL 쿼리 매개변수에 담긴 키는 허용되지 않습니다.

6개 엔드포인트

성공한 JSON 응답은 결과를 { "data": ... }에 담습니다. 결과 다운로드가 성공하면 항상 SRT를 반환합니다.

비용 추정 및 제출

두 POST 엔드포인트는 같은 JSON 요청 본문을 받습니다. Content-Type: application/json을 보내세요.

{
  "fileName": "interview.srt",
  "subtitle": "1\n00:00:01,000 --> 00:00:03,000\nHello!\n",
  "targetLanguage": "zh",
  "modelTier": "plus"
}

subtitle, targetLanguage, modelTier는 필수입니다. basic 또는 plus를 명시적으로 선택하세요. modelTier를 생략하면 400 INVALID_REQUEST를 반환합니다. 원문 언어는 자동으로 감지됩니다. 대상 언어 코드는 /api/v1/capabilities에서 확인할 수 있습니다.

선택 항목인 glossary의 각 항목에는 source와 target을 지정합니다. 선택 항목인 characters에는 이 필드들과 함께 gender(male 또는 female) 및 aliases(별칭 목록)를 지정할 수 있습니다. 정확한 구조는 OpenAPI 스키마를 참고하세요. 알 수 없는 필드는 거부됩니다.

먼저 /api/v1/translations/estimate에 POST 요청을 보내세요. creditCost, availableCredits, sufficientCredits와 자막 항목 수를 반환합니다. 비용 추정은 작업을 만들거나 크레딧을 예약하지 않습니다.

작업 생성

curl "$AST_BASE_URL/api/v1/translations" \
  -H "Authorization: Bearer $AST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: premiere-sequence-123-zh-v1' \
  --data-binary @request.json

JSON 요청 본문을 request.json으로 저장하세요. 두 환경 변수에 사이트 오리진과 API 키를 각각 설정하세요.

새 작업은 202 Accepted와 함께 data.id, data.creditCost, data.statusUrl, data.resultUrl을 반환합니다. Location 헤더는 상태 엔드포인트를 가리킵니다.

{
  "data": {
    "id": "6f476119-c02f-49a9-b61f-2b3327bd318c",
    "status": "pending",
    "fileName": "interview.srt",
    "modelTier": "plus",
    "targetLanguage": "zh",
    "creditCost": "1.00",
    "statusUrl": "/api/v1/translations/6f476119-c02f-49a9-b61f-2b3327bd318c",
    "resultUrl": "/api/v1/translations/6f476119-c02f-49a9-b61f-2b3327bd318c/result"
  }
}

새로 실행하려는 번역마다 Idempotency-Key를 생성하고 재시도 시 같은 값을 유지하세요. 동일한 요청은 HTTP 200과 함께 같은 작업을 반환합니다. 같은 키에 다른 본문을 보내면 409를 반환합니다. 멱등성 키는 계정에 속하므로 API 키를 교체한 뒤에도 유효합니다.

이 헤더에는 영문자, 숫자, 마침표, 밑줄, 콜론, 하이픈을 1–128자 사용할 수 있습니다. 재전송한 요청의 작업이 만료되었거나 삭제되었다면 410을 반환합니다. 과금 대상 작업을 새로 만들려는 경우에만 새 키를 사용하세요.

진행률과 결과

상태 URL을 5초마다 폴링하세요. 상태는 pending, processing, completed, failed 중 하나입니다. progress는 백분율이며 확인할 수 없으면 null입니다. errorCode는 작업 실패 원인을 나타냅니다.

curl --fail "$AST_BASE_URL/api/v1/translations/$TASK_ID" \
  -H "Authorization: Bearer $AST_API_KEY"

TASK_ID를 제출 응답의 data.id로 설정하세요. 진행률 응답에는 위의 작업 필드와 함께 progress, errorCode가 포함되며 둘 다 null일 수 있습니다. failed 상태가 되면 폴링을 중단하고 오류를 표시하세요. 의도적으로 번역을 새로 시도하는 경우에만 새 작업 키를 사용하세요.

완료되면 결과 URL에 GET 요청을 보내고 응답 텍스트를 SRT 파일로 저장하세요. 응답 유형은 application/x-subrip; charset=utf-8입니다. includeOriginal을 생략하거나 false로 설정하면 번역문만 반환합니다. ?includeOriginal=true를 추가하면 각 항목에서 원문 뒤에 번역문이 나오는 이중 언어 자막을 받을 수 있습니다.

curl --fail "$AST_BASE_URL/api/v1/translations/$TASK_ID/result?includeOriginal=true" \
  -H "Authorization: Bearer $AST_API_KEY" \
  --output translated-bilingual.srt

format 매개변수는 지원하지 않으며 사용하면 400 INVALID_REQUEST를 반환합니다. 오류는 JSON으로 반환됩니다. 완료 전에 결과를 요청하면 409 TRANSLATION_NOT_READY와 Retry-After: 5를 반환합니다. 번역이 실패한 경우 409 TRANSLATION_FAILED를 반환합니다.

완료된 결과는 바로 다운로드하세요. 웹사이트의 삭제 및 보관 규칙은 API 작업에도 적용됩니다. 작업이 없거나 접근할 수 없으면 404를 반환합니다. API 작업은 자막 기록에도 표시됩니다.

크레딧과 제한

API 번역은 기존 계정 크레딧을 사용하며 웹사이트의 모델 등급별 가격과 최소 요금이 적용됩니다. 별도의 API 추가 요금은 없습니다. 파일마다 비용 추정 엔드포인트를 사용하세요. 추정 가격은 고정되지 않습니다. 수락된 작업의 creditCost가 예약되는 크레딧 양입니다.

작업이 대기 중이거나 처리 중일 때 크레딧을 예약하고, 성공적으로 완료되면 한 번만 과금합니다. 대기 중 원래 유효 기간이 지나더라도 예약된 크레딧은 해당 작업에 사용할 수 있습니다. 실패하거나 삭제하면 예약이 해제됩니다. 만료되지 않은 크레딧은 사용 가능 잔액으로 돌아가고 만료된 크레딧은 만료 상태를 유지합니다. 실패한 작업에는 번역 요금이 부과되지 않습니다. 잔액 엔드포인트는 십진수 문자열로 availableCredits, reservedCredits, totalCredits(사용 가능 크레딧과 예약된 크레딧의 합계)를 반환합니다.

{ "data": { "availableCredits": "9.00", "reservedCredits": "1.00", "totalCredits": "10.00" } }

• 계정당 60초 구간에서 최대 60회 요청할 수 있으며 모든 키가 한도를 공유합니다.
• 구간당 최대 10회 POST 요청할 수 있으며 비용 추정과 작업 제출이 한도를 공유합니다.
• 대기 중이거나 처리 중인 API 작업은 동시에 최대 3개입니다.
• 작업당 파일 하나와 대상 언어 하나만 사용할 수 있습니다.
• UTF-8 자막 텍스트 최대 1 MiB, 전체 JSON 최대 2 MiB, 자막 항목 최대 5,000개입니다.
• 자막 항목별 텍스트 길이는 웹사이트 설정을 따르며 기본값은 500자입니다.
• 용어집 항목 최대 200개, 등장인물 최대 100명, 인물별 별칭 최대 20개입니다. 용어와 이름은 최대 200자입니다.

현재 제한은 /api/v1/capabilities에서 확인하세요. 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset(Unix 시간, 초 단위)이 포함됩니다. 429 응답에서는 Retry-After를 따르세요. 번역 완료 시간은 대기열과 입력 내용에 따라 달라집니다.

오류와 재시도

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account does not have enough available credits."
  },
  "requestId": "..."
}

400: 잘못된 입력. 401: 유효하지 않거나 폐기된 키. 402: 크레딧 부족. 404: 작업이 없거나 접근할 수 없음. 409: 키 충돌, 미완료 또는 실패한 번역. 410: 재전송 요청에 해당하는 작업이 만료됨. 413: 입력이 너무 큼. 415: JSON 필요. 422: 자막이 거부됨. 429: 요청 수 또는 활성 작업 한도 초과. 502: 불완전한 결과. 503: 서비스, 모델 또는 대기열을 사용할 수 없음.

네트워크 오류나 일시적인 서버 장애가 발생하면 같은 Idempotency-Key와 본문으로 재시도하세요. Retry-After가 있으면 지정된 시간만큼 기다리세요. 번역이 최종 실패한 뒤 의도적으로 다시 번역하려면 새 키가 필요합니다. 지원팀에 문의할 때는 X-Request-Id와 작업 ID를 함께 알려주세요.

Premiere Pro 워크플로

1. SRT 파일을 선택하거나 내보내세요.
2. 비용을 추정하고 선택한 대상 언어로 작업을 제출하세요.
3. 작업 진행률을 표시한 다음 번역된 SRT를 저장하세요.
4. Premiere로 가져와 자막 트랙에 배치하세요.

UXP 매니페스트의 네트워크 권한에 이 오리진을 선언하고 SRT 읽기와 쓰기를 위한 파일 접근 권한을 요청하세요. 공개 엔드포인트는 쿠키 없이 Bearer 인증을 사용하는 CORS 요청을 지원합니다.

번호가 있는 SRT 항목을 사용하고 시간 형식은 HH:MM:SS,mmm으로 지정하세요. 텍스트는 비어 있으면 안 되며 항목 사이에는 빈 줄을 넣어야 합니다. 기존 자막 정리 규칙도 적용됩니다. 서식 태그가 제거되고 번호가 다시 매겨지며 겹치는 보조 오버레이 텍스트가 필터링될 수 있습니다. 유지되는 항목의 타임스탬프는 보존됩니다. SRT에는 Premiere 스타일이 포함되지 않습니다.

기존 자막 트랙에 자동으로 접근하는 기능은 사용 중인 Premiere 버전에서 별도로 확인해야 합니다. API는 자막 텍스트를 받으므로 오디오는 제출 전에 자막으로 전사하세요.