Skip to main content
POST
본인 소유의 참조 이미지 업로드에 사용할 서명된 PUT URL을 조회합니다. 8 MiB 이미지는 최대 두 파트로 구성됩니다. upload_complete에 사용할 수 있도록 각 PUT이 반환한 ETag를 저장하세요.

인증 및 권한

string
필수
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이 REST 엔드포인트에서는 사용할 수 없습니다.
필요한 권한: thumbnails:write. 활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.

매개변수

string
전송 계층에서는 선택 사항입니다. 생략하면 서버가 유효성 검사 전에 식별자를 추가합니다. 응답이 유실된 경우 안전하게 복구할 수 있도록 고정된 UUID v4를 직접 제공하세요.형식: “uuid”. 패턴: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
string
필수
이 도메인의 upload_initialize 액션이 반환한 uploadId입니다.형식: “uuid”. 패턴: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.
array
필수
값 목록입니다. 항목 구조는 전체 입력 스키마를 참고하세요.최소 항목 수: 1. 최대 항목 수: 2.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

멱등성

각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요.

요청 예제

예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.

응답

성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다. 중복되지 않는 요청 파트 번호마다 하나씩 제공되는 임시 서명 PUT URL의 배열입니다. 응답에는 이미지 바이트, ETags 또는 파트별 크기 필드가 없습니다.

결과 필드

이 요청 복구 및 폴링

연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요.
HTTP 200

작업 참고 사항

  • thumbnails:write가 필요하며 추가 업로드 범위는 필요하지 않습니다.
  • uploadId는 initialize에서 받은 UUID입니다. partNumbers에는 각각 1에서 2 사이인 정수가 1–2개 포함되며, 각 파트는 해당 세션의 선언된 fileSize에 대해 존재해야 합니다. 요청한 파트 번호가 중복되면 하나의 URL로 합쳐집니다.
  • 반환된 각 URL에 파트의 원시 바이너리 바이트를 PUT으로 전송하세요. Content-Length는 서명에 포함되며 min(partSize, fileSize - (partNumber - 1) × partSize)와 정확히 일치해야 합니다. 7 MiB 예시에서 파트 1은 5,242,880바이트이고 파트 2는 2,097,152바이트입니다. 서명된 URL에 JSON, multipart/form-data 또는 base64를 전송하지 마세요.
  • 성공한 각 PUT의 ETag 응답 헤더를 저장하고 그 값을 thumbnails_upload_complete에 보내세요. 서명된 URL은 비공개 임시 업로드 권한으로 취급하세요.
  • 연결된 사용자에게 속한 업로드만 서명, 완료 처리 또는 중단할 수 있습니다. 이 별칭은 다른 업로드 계열을 통해 생성된 세션이더라도 최대 8 MiB의 JPG, PNG 및 WebP 세션만 허용합니다.
  • 프로덕션 업로드 세션은 24시간 후에 만료됩니다. 서명된 파트 URL은 한 시간 후에 만료됩니다. 완료와 중단은 활성 세션을 제거하며, 이후 sign-parts와 complete는 Upload not found를 반환합니다. 어느 응답에도 expiresAt 필드는 포함되지 않습니다.
  • UUID v4 requestId 또는 HTTP Idempotency-Key 헤더를 사용하고 재시도 시 동일한 입력과 함께 재사용하세요. 통합 계층은 각 변경을 기록하고 다시 실행하지 않은 채 기록된 상태 또는 결과를 반환합니다. failed 또는 interrupted 상태의 요청은 자동으로 재시도되지 않습니다.
  • URL이 1시간 후 만료된 뒤에도 세션이 활성 상태라면, 새 requestId로 sign-parts를 호출하여 새 URL을 받으세요. 동일한 requestId로 다시 시도하면 이전 URL을 포함한 저장된 결과를 반환합니다.

사용량

성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.

오류