본문으로 건너뛰기

Jobs

영상과 이미지 작업의 진행 상태와 결과 조회

작업 ID로 조회하는 응답에서 생성 상태, 결과 미디어의 준비 상태와 비용을 읽는 방법 및 조회 오류의 처리 기준을 설명합니다.

페이지 목차
GET
https://gw.letsur.ai/v1/jobs/{id}
인증Authorization: Bearer <API_KEY>

조회할 작업과 인증

이 엔드포인트로 영상 작업과 이미지 작업의 상태, 결과 파일과 비용을 조회합니다. 이미지 작업은 작업 ID를 반환하는 모델로 Image Generations 요청을 보내면 만들어집니다. 작업의 상태를 확인한 뒤 파일을 받는 순서는 생성 요청하고 결과 파일 받기의 상태 확인하기에서 확인합니다.

{id}에는 다음 값 중 하나를 넣습니다. 모델이 달라도 조회 방법은 같습니다.

  • 영상 작업: Video Generations 접수 응답의 id. 모델과 관계없이 이 필드에 있습니다.
  • 이미지 작업: Image Generations 동기 응답의 id나 비동기 접수 응답의 id. 둘 다 조회에 쓸 수 있습니다. 결과를 응답 본문으로 받는 모델의 응답에는 작업 ID가 없습니다.

Chat Completions처럼 다른 API 응답에 있는 ID로는 조회하지 않습니다.

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

조회 요청 예시

cURL과 Python 예제는 서버 환경 변수 LETSUR_API_KEY와 접수 응답의 ID를 저장한 환경 변수 JOB_ID를 사용합니다.

Python 예제는 Python 3에서 실행합니다. 예제는 요청을 자동으로 재시도하지 않습니다. 오류 응답이나 서명 링크가 포함된 출력은 공개 로그에 남기지 마세요.

cURL
curl --fail-with-body "https://gw.letsur.ai/v1/jobs/$JOB_ID" \ -H "Authorization: Bearer $LETSUR_API_KEY"

조회에 성공하면 응답의 data.job.status를 확인합니다. HTTP 200만으로 생성 성공을 판단하지 않습니다.

응답과 상태

HTTP 200 응답의 data.job에 작업 정보가 들어 있습니다. 아래는 영상 작업이 대기 중일 때의 설명용 응답이며 예시 모델은 Seedance 2.5입니다.

{ "data": { "job": { "id": "lst-example-job-id", "id_scheme": "letsur_job_id", "model": "dreamina-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" } } }

data.job에서 주로 읽는 필드는 다음과 같습니다. 작업이 대기 중이거나 처리 중이면 응답에 result와 error가 없습니다.

필드설명
model작업을 제출할 때 지정한 모델 코드
status작업 상태. 아래 상태 표 참고
result성공한 작업에 포함되며 storage 값과 media 배열을 담음. 결과 파일 참고
error작업이 실패하면 포함되며 type, title, detail, vendor_code를 담음. vendor_code는 null일 수 있음
usage비용이 계산되면 추가됨. 사용량과 작업 비용 참고
seed시드 값. 있을 때만 반환됨

data.job.status 값은 다음과 같습니다.

상태뜻과 다음 행동
queued접수 후 대기 중
running처리 중. 이미지 작업은 동기 응답을 받은 직후에도 결과 파일 준비가 시작될 때까지 이 상태로 보일 수 있음
succeeded생성 성공. 파일 준비 상태는 result.media에서, 비용은 usage에서 따로 확인
failed작업 실패. 원인은 error에서 확인

failed에는 생성 중 오류뿐 아니라 제출 실패, 대기 만료, 결과 확인 실패로 작업이 실패로 확정된 경우도 포함됩니다. 어느 단계에서 실패했는지는 error.type과 상세 내용으로 확인합니다. data.job.error는 작업 실패 정보이며, 조회 요청 자체가 실패한 HTTP 조회 오류와 다릅니다.

상태별 다음 행동은 영상 작업과 이미지 작업 모두 생성 요청하고 결과 파일 받기의 상태 확인하기에 있습니다. 이미지 작업의 error.type 값은 Image Generations의 작업 실패 사유에 있습니다. 모델마다 더해지는 결과 필드는 모델 가이드에 있습니다.

결과 파일

성공한 작업의 data.job.result에는 storage 값과 media 배열이 포함됩니다. 결과 미디어가 있으면 storage는 letsur입니다. 미디어가 없으면 storage는 none이고 media는 빈 배열일 수 있습니다.

media 배열의 각 항목에는 다음 필드가 있습니다.

필드설명
media_id문자열. 결과 파일의 미디어 ID. 영상 결과는 이 값으로 Media Links에서 다운로드 링크를 발급받음
kind문자열. 영상과 이미지 등 결과의 종류
state문자열. 파일의 준비 상태. 아래 상태 표 참고
url문자열 또는 null. 다운로드 링크. 링크를 만들 수 있을 때 추가됨
url_expires_at정수. 링크 만료시각(Unix 초). url과 함께 추가됨
url_unavailable_reason문자열. 링크를 받을 수 없는 이유. copying, failed, retention_expired가 나타날 수 있음

파일이 준비 중이거나 만료되면 링크 값이 null이고 url_unavailable_reason에 이유가 나타날 수 있습니다. 링크 필드는 생략될 수도 있으므로 항상 있다고 가정하지 않습니다.

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

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

각 항목의 state 값은 다음과 같습니다.

상태뜻과 다음 행동
pending파일 준비 중
ready파일 준비됨. 받는 경로는 표 아래 참고
unavailable파일 사용 불가. 이유는 url_unavailable_reason에 표시될 수 있음

ready인 파일을 받는 경로는 작업 종류에 따라 다릅니다.

작업 응답의 미디어 항목에는 파일 보관 만료시각 expires_at이 포함되지 않습니다. 영상 결과에 링크가 없거나 파일 보관 만료시각을 알아야 하면, 반환된 media_id로 파일 링크 발급을 요청해 파일 준비와 만료 상태를 확인합니다. 이미지 결과의 링크가 만료되면 같은 작업을 다시 조회해 새 링크를 받습니다.

사용량과 작업 비용

비용이 계산되면 data.job.usage가 추가됩니다.

필드설명
amount문자열(소수). 계산된 작업 비용
currency문자열. amount의 단위
items배열. 사용량 항목 목록
items[].quantity문자열(소수). 사용량
items[].unit문자열. 사용량의 단위. 생략될 수 있음
items[].unit_price문자열(소수). 적용 단가. 생략될 수 있음

다음은 필드 구조만 보여 주는 설명용 값이며 현재 단가가 아닙니다.

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

이미지 작업의 items는 모델에 따라 이미지 종류별로 장 수를 세는 항목으로 나뉘어 반환되거나, unit이 없는 항목 하나로 반환됩니다. 항목의 단위 값은 모델 가이드에 있습니다. 어느 경우든 작업 비용은 amount입니다.

usage가 있을 때와 없을 때 각각 무엇을 뜻하는지, 스페이스의 최종 차감과 어떤 관계인지는 요청별 비용의 비동기 영상 작업 비용 확인하기에 있습니다. 이미지 작업의 비용 기록은 요청별 비용에서 확인합니다.

오류와 복구

다음 조회 오류는 최상위 error 객체의 code, message로 반환됩니다. 실패한 작업의 data.job.error와 혼동하지 마세요.

오류원인과 할 일
job_not_found (404)작업이 없거나 조회한 스페이스가 다릅니다. 두 경우 모두 같은 형태로 반환됩니다. ID가 접수 응답의 값인지, 키가 작업을 만든 스페이스의 키인지 확인합니다
result_unavailable (503)결과를 일시적으로 조회할 수 없습니다. 생성 POST 대신 같은 ID로 다시 조회합니다