Jobs

영상 생성 작업의 상태와 결과 파일, 비용을 확인하세요.

Video Generations의 작업 ID로 조회하며 생성에 성공해도 파일은 준비 중일 수 있습니다.

GEThttps://gw.letsur.ai/v1/jobs/{id}

AUTHAuthorization: Bearer <API_KEY>

조회할 작업과 인증

Seedance Video Generations 응답의 id로 작업을 조회합니다. Chat Completions 같은 다른 응답의 ID를 대신 넣지 않습니다.

요청 URL은 https://gw.letsur.ai/v1/jobs/{id}입니다. 작업을 만든 스페이스의 AI 게이트웨이 API 키를 사용하며 요청 본문은 없습니다. 키 설정은 인증과 요청 헤더를 확인합니다.

응답과 상태

HTTP 200의 작업은 data.job에 있습니다. 아래는 대기 중인 작업의 설명용 응답입니다.


{
  "data": {
    "job": {
      "id": "lst-example-job-id",
      "id_scheme": "letsur_job_id",
      "model": "byteplus-seedance-2.5",
      "space_id": "example-space-id",
      "status": "queued",
      "created_at": "2026-09-11T01:00:00.000Z",
      "updated_at": "2026-09-11T01:00:00.000Z"
    }
  }
}

`status`	의미	다음 행동
`queued`	접수 후 대기 중	같은 ID로 나중에 조회
`running`	처리 중	같은 ID로 나중에 조회
`succeeded`	생성 성공	`result.media`의 파일 상태와 `usage`를 각각 확인
`failed`	작업 실패	`error`를 확인하고 입력 정정 또는 지원 요청

failed에는 생성 중 오류뿐 아니라 제출 실패, 대기 만료나 결과를 확인하지 못해 작업이 실패로 확정된 경우도 포함됩니다. error.type과 상세 내용으로 실패 단계를 확인합니다.

대기 및 처리 중에는 result와 error가 없습니다. 실패하면 data.job.error에 type, title, detail, vendor_code가 들어옵니다. vendor_code는 null일 수 있습니다. HTTP 조회 오류와 작업 실패는 서로 다릅니다.

결과 파일

성공한 작업의 data.job.result는 storage와 media 배열을 포함합니다. 결과 미디어가 있으면 storage는 letsur이며, 미디어가 없는 경우 none과 빈 배열일 수 있습니다.

다음은 result 부분의 설명용 예시입니다.


{
  "storage": "letsur",
  "media": [
    {"media_id": "example-media-id", "kind": "video", "state": "ready"}
  ]
}

각 항목의 state는 pending(파일 준비 중), ready(파일 준비됨), unavailable(파일 사용 불가)입니다. kind로 영상과 이미지 등 결과 종류를 구분합니다.

다운로드 링크를 만들 수 있으면 항목에 url과 Unix 초 단위 url_expires_at이 추가됩니다. 준비 중이거나 만료된 파일은 값이 null이고 url_unavailable_reason에 copying, failed, retention_expired가 나타날 수 있습니다. 링크 필드는 생략될 수도 있으므로 항상 있다고 가정하지 않습니다.

링크가 없으면 반환된 media_id로 파일 링크 발급을 요청해 파일 준비와 만료 상태를 확인합니다. 이 작업 응답의 미디어 항목에는 파일 보관 만료시각 expires_at이 포함되지 않습니다.

사용량과 작업 비용

비용이 계산되면 data.job.usage가 추가됩니다. 다음은 필드 구조만 보여 주는 설명용 값이며 현재 단가가 아닙니다.


{
  "amount": "1.20",
  "currency": "unit",
  "items": [
    {"quantity": "100000", "unit": "token", "unit_price": "0.000012"}
  ]
}

amount는 계산된 작업 비용, items[].quantity는 사용량, unit_price는 적용 단가입니다. 세 값은 소수 문자열이며 unit_price는 생략될 수 있습니다. 응답에 시드가 있으면 data.job.seed로 반환합니다.

usage가 없다고 무료인 것은 아니며, 값이 있다고 스페이스의 최종 차감까지 완료됐다는 뜻도 아닙니다. 요청별 비용에서 작업 비용과 집계, 잔액을 구분해 확인합니다.

조회 오류와 재시도

HTTP	`error.code`	대응
404	`job_not_found`	ID가 접수 응답의 값인지와 키의 스페이스를 확인
503	`result_unavailable`	결과 조회가 일시적으로 불가함. 생성 POST 대신 같은 ID로 재조회

이 오류는 최상위 error 객체의 code, message로 반환됩니다. 404는 작업이 없거나 조회 스페이스가 다를 때 같은 형태를 사용합니다. 실패한 작업의 data.job.error와 혼동하지 않습니다.

실제 요청부터 파일과 비용을 확인하는 순서는 영상 생성하고 파일 받기를 따릅니다.