API 참조

동영상 작업 상태 조회

GET/v1/videos/{task_id}

상태를 조회합니다. 생성 성공, billing.status와 storage.status는 독립적으로 판단해야 합니다. 할당량이 소진된 유효한 키로 작업을 조회할 수 있으며 현재 모델 권한은 이 구현에 따라 검사합니다.

인증과 권한

현재 GloopAPI 키를 사용하세요. 사용 가능한 모델, 기능과 권한은 해당 카탈로그와 엔드포인트 문서에 따라 달라집니다.

Authorization: Bearer $GLOOP_API_KEY

인증 방식: BearerAuth

요청

경로 매개변수

  • task_idstring필수

    동일 키로 생성한 작업의 공개 ID입니다.

응답과 오류

HTTP 200

요청에 성공했습니다.

application/json

유형
object
필수 필드
idmodelstatuscreated_at
  • updated_atinteger선택 사항

    Unix 초 단위 마지막 갱신 시각입니다.

  • retentionstring선택 사항

    작업 결과 보관 정책이며 persistent는 영구 보관 작업 공간입니다.

  • inputobject선택 사항

    원래 작업 입력 또는 도구 계약 입력입니다.

    input 하위 필드(14)
    • modestring선택 사항

      persistent에서 필수입니다.

      열거형
      ["text_to_video","image_to_video"]
    • retentionstring선택 사항

      persistent는 영구 보관 작업 공간을 사용하며 생략하면 일반 작업을 생성합니다.

    • quote_idstring선택 사항

      새 persistent 요청은 먼저 video-quotes가 반환한 유효한 견적을 확인해야 합니다.

    • start_frameobject선택 사항

      persistent 이미지-동영상 생성에 필수인 동일 키 소유의 관리형 파일입니다. 텍스트-동영상 생성에는 금지됩니다.

      start_frame 하위 필드(1)
      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

      allOf 분기 1

      유형: object

      이 분기의 필수 항목: file_id

      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

    • end_frameobject선택 사항

      persistent의 선택적 마지막 프레임이며 해당 기능이 지원해야 합니다.

      end_frame 하위 필드(1)
      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

      allOf 분기 1

      유형: object

      이 분기의 필수 항목: file_id

      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

    • webhook_endpoint_idstring선택 사항

      일반 작업은 콘솔에 설정된 수신자를 참조할 수 있으며 persistent에서는 금지됩니다.

    • modelstring필수

      현재 키의 카탈로그에 있는 공개 모델 ID이며 과거 서비스 모델이 계속 사용 가능하다고 보장하지 않습니다.

    • promptstring필수

      생성 프롬프트입니다.

      최소 길이
      1
      최대 길이
      2500
    • durationinteger선택 사항

      모델별 초 단위 길이입니다. video-models mode.presets의 완전한 조합을 사용하고 데카르트 곱을 만들지 마세요. Wan Turbo는 이 필드를 지원하지 않으며 공통 기본값은 없습니다.

    • image_urlstring선택 사항

      일반 작업 전용인 모델별 공개 HTTPS 첫 프레임이며 persistent에서는 금지됩니다.

    • end_image_urlstring선택 사항

      일반 작업 전용인 모델별 공개 HTTPS 마지막 프레임이며 persistent에서는 금지됩니다.

    • resolutionstring선택 사항

      모델 프리셋의 해상도 값입니다.

    • aspect_ratiostring선택 사항

      모델 프리셋의 화면비 값입니다.

    • generate_audioboolean선택 사항null 허용

      모델에 따라 다르므로 모드의 오디오 정책과 프리셋을 사용하세요. 모든 모델이 오디오를 생성한다고 가정하지 마세요.

    allOf 분기 1

    유형: object

    이 분기의 필수 항목: model, prompt

    추가 속성: false

    • modestring선택 사항

      persistent에서 필수입니다.

      열거형
      ["text_to_video","image_to_video"]
    • retentionstring선택 사항

      persistent는 영구 보관 작업 공간을 사용하며 생략하면 일반 작업을 생성합니다.

    • quote_idstring선택 사항

      새 persistent 요청은 먼저 video-quotes가 반환한 유효한 견적을 확인해야 합니다.

    • start_frameobject선택 사항

      persistent 이미지-동영상 생성에 필수인 동일 키 소유의 관리형 파일입니다. 텍스트-동영상 생성에는 금지됩니다.

      start_frame 하위 필드(1)
      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

      allOf 분기 1

      유형: object

      이 분기의 필수 항목: file_id

      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

    • end_frameobject선택 사항

      persistent의 선택적 마지막 프레임이며 해당 기능이 지원해야 합니다.

      end_frame 하위 필드(1)
      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

      allOf 분기 1

      유형: object

      이 분기의 필수 항목: file_id

      • file_idstring필수

        동일 계정/키의 관리형 파일 공개 ID입니다.

    • webhook_endpoint_idstring선택 사항

      일반 작업은 콘솔에 설정된 수신자를 참조할 수 있으며 persistent에서는 금지됩니다.

    • modelstring필수

      현재 키의 카탈로그에 있는 공개 모델 ID이며 과거 서비스 모델이 계속 사용 가능하다고 보장하지 않습니다.

    • promptstring필수

      생성 프롬프트입니다.

      최소 길이
      1
      최대 길이
      2500
    • durationinteger선택 사항

      모델별 초 단위 길이입니다. video-models mode.presets의 완전한 조합을 사용하고 데카르트 곱을 만들지 마세요. Wan Turbo는 이 필드를 지원하지 않으며 공통 기본값은 없습니다.

    • image_urlstring선택 사항

      일반 작업 전용인 모델별 공개 HTTPS 첫 프레임이며 persistent에서는 금지됩니다.

    • end_image_urlstring선택 사항

      일반 작업 전용인 모델별 공개 HTTPS 마지막 프레임이며 persistent에서는 금지됩니다.

    • resolutionstring선택 사항

      모델 프리셋의 해상도 값입니다.

    • aspect_ratiostring선택 사항

      모델 프리셋의 화면비 값입니다.

    • generate_audioboolean선택 사항null 허용

      모델에 따라 다르므로 모드의 오디오 정책과 프리셋을 사용하세요. 모든 모델이 오디오를 생성한다고 가정하지 마세요.

  • billingobject선택 사항

    독립적인 요금 상태이며 생성 상태로 대체하지 마세요.

    billing 하위 필드(7)
    • currencystring필수

      견적/요금 통화입니다.

    • error_codestring선택 사항

      분기 로직에 사용할 수 있는 공개 오류 코드입니다.

    • statusstring필수

      현재 객체 상태입니다. 요금 및 저장 단계와 별도로 판단하세요.

    • reserved_quotainteger필수

      플랫폼 할당량 단위의 예약량이며 USD 금액이 아닙니다.

    • final_quotainteger필수null 허용

      플랫폼 할당량 단위의 최종 과금액이며 null은 아직 확정되지 않았음을 뜻합니다.

    • reserved_amountstring필수

      견적 통화 단위의 최대 예약액 문자열입니다.

    • final_amountstring필수null 허용

      최종 과금액 문자열이며 null은 미정산을 뜻합니다.

    allOf 분기 1

    유형: object

    이 분기의 필수 항목: currency, status, reserved_quota, final_quota, reserved_amount, final_amount

    • currencystring필수

      견적/요금 통화입니다.

    • error_codestring선택 사항

      분기 로직에 사용할 수 있는 공개 오류 코드입니다.

    • statusstring필수

      현재 객체 상태입니다. 요금 및 저장 단계와 별도로 판단하세요.

    • reserved_quotainteger필수

      플랫폼 할당량 단위의 예약량이며 USD 금액이 아닙니다.

    • final_quotainteger필수null 허용

      플랫폼 할당량 단위의 최종 과금액이며 null은 아직 확정되지 않았음을 뜻합니다.

    • reserved_amountstring필수

      견적 통화 단위의 최대 예약액 문자열입니다.

    • final_amountstring필수null 허용

      최종 과금액 문자열이며 null은 미정산을 뜻합니다.

  • storageobject선택 사항

    독립적인 파일 저장 상태입니다.

    storage 하위 필드(3)
    • file_idstring선택 사항

      동일 계정/키의 관리형 파일 공개 ID입니다.

    • statusstring필수

      현재 객체 상태입니다. 요금 및 저장 단계와 별도로 판단하세요.

    • error_codestring선택 사항

      분기 로직에 사용할 수 있는 공개 오류 코드입니다.

    allOf 분기 1

    유형: object

    이 분기의 필수 항목: status

    • file_idstring선택 사항

      동일 계정/키의 관리형 파일 공개 ID입니다.

    • statusstring필수

      현재 객체 상태입니다. 요금 및 저장 단계와 별도로 판단하세요.

    • error_codestring선택 사항

      분기 로직에 사용할 수 있는 공개 오류 코드입니다.

  • availabilityobject선택 사항

    현재 가능한 작업입니다.

    availability 하위 필드(4)
    • can_cancelboolean필수

      현재 작업의 취소 요청 허용 여부입니다.

    • can_deleteboolean필수

      현재 작업의 삭제 허용 여부입니다.

    • can_retry_storageboolean필수

      현재 작업의 저장 재시도 허용 여부입니다.

    • reasonstring선택 사항

      작업 불가 또는 요금 검토의 공개 사유입니다.

    allOf 분기 1

    유형: object

    이 분기의 필수 항목: can_cancel, can_delete, can_retry_storage

    • can_cancelboolean필수

      현재 작업의 취소 요청 허용 여부입니다.

    • can_deleteboolean필수

      현재 작업의 삭제 허용 여부입니다.

    • can_retry_storageboolean필수

      현재 작업의 저장 재시도 허용 여부입니다.

    • reasonstring선택 사항

      작업 불가 또는 요금 검토의 공개 사유입니다.

  • idstring필수

    해당 상세 경로에 사용하는 이 객체의 공개 식별자입니다.

  • modelstring필수

    현재 키의 카탈로그에 있는 공개 모델 ID입니다.

  • statusstring필수

    일반/영구 보관 작업 상태로 pending_dispatch/submitting/queued/processing/succeeded/failed/cancelled/unknown일 수 있습니다. 종료 상태가 요금 정산이나 보관 준비 완료를 뜻하지는 않습니다.

  • created_atinteger필수

    Unix 초 단위 생성 시각입니다.

  • resultobject선택 사항

    준비된 결과의 메타데이터이며 완료 전에는 없을 수 있습니다.

    result 하위 필드(8)
    • file_idstring선택 사항

      동일 계정/키의 관리형 파일 공개 ID입니다.

    • storage_statusstring선택 사항

      파일 보관 상태이며 관리형 다운로드는 ready 이후에만 보장됩니다.

    • deliverystring선택 사항

      authenticated_content는 콘텐츠 경로를 사용해야 함을 뜻합니다. 직접 URL이 있다고 가정하지 마세요.

    • content_pathstring선택 사항

      플랫폼 인증 콘텐츠 경로입니다. 동일한 키로 바이너리 콘텐츠를 요청하세요.

    • urlstring선택 사항

      결과 또는 참조의 접근 URL입니다. 서명 URL은 짧은 시간 동안만 유효합니다.

    • content_typestring선택 사항

      결과 MIME 유형입니다.

    • file_namestring선택 사항

      공개 다운로드 파일명입니다.

    • file_sizeinteger선택 사항

      바이트 단위 결과 파일 크기입니다.

    allOf 분기 1

    유형: object

    • file_idstring선택 사항

      동일 계정/키의 관리형 파일 공개 ID입니다.

    • storage_statusstring선택 사항

      파일 보관 상태이며 관리형 다운로드는 ready 이후에만 보장됩니다.

    • deliverystring선택 사항

      authenticated_content는 콘텐츠 경로를 사용해야 함을 뜻합니다. 직접 URL이 있다고 가정하지 마세요.

    • content_pathstring선택 사항

      플랫폼 인증 콘텐츠 경로입니다. 동일한 키로 바이너리 콘텐츠를 요청하세요.

    • urlstring선택 사항

      결과 또는 참조의 접근 URL입니다. 서명 URL은 짧은 시간 동안만 유효합니다.

    • content_typestring선택 사항

      결과 MIME 유형입니다.

    • file_namestring선택 사항

      공개 다운로드 파일명입니다.

    • file_sizeinteger선택 사항

      바이트 단위 결과 파일 크기입니다.

  • errorstring선택 사항

    공개 실패 분류 또는 오류 객체입니다.

HTTP 401

키가 없거나 유효하지 않거나 만료 또는 폐기되었습니다.

application/json

유형
object
필수 필드
error

HTTP 403

현재 키에 권한이 없습니다.

application/json

유형
object
필수 필드
error
  • errorobject필수
    error 하위 필드(3)
    • messagestring필수
    • typestring필수
      열거형
      ["new_api_error"]
    • codestring필수

HTTP 404

객체 또는 기능을 사용할 수 없습니다.

application/json

유형
object
필수 필드
error
  • errorobject필수
    error 하위 필드(3)
    • messagestring필수
    • typestring필수
      열거형
      ["new_api_error"]
    • codestring필수

HTTP 409

요청 충돌, 준비되지 않음 또는 제출 결과 불명확입니다. 먼저 원래 기록을 조회하고 무조건 재전송하지 마세요.

application/json

유형
object
필수 필드
error
  • errorobject필수
    error 하위 필드(3)
    • messagestring필수
    • typestring필수
      열거형
      ["new_api_error"]
    • codestring필수

HTTP 410

동영상 작업이 삭제되어(task_deleted) 더 이상 읽을 수 없습니다.

application/json

유형
object
필수 필드
error

HTTP 429

요청/대기열 속도 제한입니다.

application/json

유형
object
필수 필드
error

HTTP 500

내부 인증 또는 데이터 저장 오류입니다.

application/json

유형
object
필수 필드
error

HTTP 502

서비스 응답 오류입니다.

application/json

유형
object
필수 필드
error
  • errorobject필수
    error 하위 필드(3)
    • messagestring필수
    • typestring필수
      열거형
      ["new_api_error"]
    • codestring필수

HTTP 503

서비스, 스토리지, 가격을 일시적으로 사용할 수 없습니다.

application/json

유형
object
필수 필드
error
  • errorobject필수
    error 하위 필드(3)
    • messagestring필수
    • typestring필수
      열거형
      ["new_api_error"]
    • codestring필수
개발할 준비가 되셨나요? 열기: 콘솔 API 키를 생성하거나 살펴보기: 기능.