API 참조

동영상 생성 작업 만들기

POST/v1/videos

영구 백그라운드 작업자가 디스패치, 폴링, 요금 정산과 저장을 처리합니다. 클라이언트 조회는 상태만 관찰하고 정산을 유발하지 않습니다. 일반/영구 보관 요청은 각각의 모델/관리형 프레임/견적 제약을 따릅니다. unknown/submission_state_unknown에서는 다른 요청 키로 무조건 재전송하지 마세요.

일반 워크플로와 영구 보관 워크플로

일반 동영상은 모델의 공개 HTTPS 입력을 사용합니다. 영구 보관 동영상은 retention=persistent, 기능 카탈로그의 완전한 프리셋, 관리형 프레임과 유효한 견적을 사용합니다. 일반 요청에 작업 공간 프레임 필드를 섞거나 서로 다른 프리셋의 매개변수를 새 조합으로 만들지 마세요.

백그라운드 처리가 실행, 정산과 저장을 진행하고 클라이언트 조회는 기록만 관찰합니다. 예상 예약액은 추가 청구나 환불이 필요할 수 있습니다. 성공 후 저장에 실패하면 다시 생성하지 말고 원래 결과의 보관을 재시도하세요. 제출 결과가 불명확하면 먼저 원래 요청 키로 복구하세요. 비동기 작업과 멱등성을 참고하세요.

인증과 권한

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

Authorization: Bearer $GLOOP_API_KEY

인증 방식: BearerAuth

요청

요청 헤더

Idempotency-Keystring필수
최소 길이
1
최대 길이
191
패턴
"^[\\x20-\\x7E]{1,191}$"

요청 본문 · application/json

유형: object
필수 필드: modelprompt
추가 속성: 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 허용
모델에 따라 다르므로 모드의 오디오 정책과 프리셋을 사용하세요. 모든 모델이 오디오를 생성한다고 가정하지 마세요.

응답과 오류

HTTP 202

작업이 접수되었으며 완료를 뜻하지는 않습니다.

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 400

요청 매개변수가 유효하지 않습니다.

application/json

유형: object
필수 필드: error

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

HTTP 401

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

application/json

유형: object
필수 필드: error

errorobject필수
error 하위 필드(4)
- codestring선택 사항
- messagestring선택 사항
- typestring선택 사항
- request_idstring선택 사항

HTTP 402

계정 또는 키의 사용 가능한 할당량이 부족합니다.

application/json

유형: object
필수 필드: error

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

HTTP 403

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

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 429

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

application/json

유형: object
필수 필드: error

errorobject필수
error 하위 필드(4)
- codestring선택 사항
- messagestring선택 사항
- typestring선택 사항
- request_idstring선택 사항

HTTP 500

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

application/json

유형: object
필수 필드: error

errorobject필수
error 하위 필드(4)
- codestring선택 사항
- messagestring선택 사항
- typestring선택 사항
- request_idstring선택 사항

HTTP 503

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

application/json

유형: object
필수 필드: error

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