curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_complete' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"b7d73225-716b-45ec-ae43-559cfb3b6412","uploadId":"c547fb7f-f334-46a8-a8bb-80b5b343889a","parts":[{"partNumber":1,"etag":"\"d41d8cd98f00b204e9800998ecf8427e\""},{"partNumber":2,"etag":"\"0cc175b9c0f1b6a831c399e269772661\""}]}'
const input = {
requestId: 'b7d73225-716b-45ec-ae43-559cfb3b6412',
uploadId: 'c547fb7f-f334-46a8-a8bb-80b5b343889a',
parts: [
{
partNumber: 1,
etag: '"d41d8cd98f00b204e9800998ecf8427e"',
},
{
partNumber: 2,
etag: '"0cc175b9c0f1b6a831c399e269772661"',
},
],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_complete', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/images_upload_complete",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412", "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "parts": [{"partNumber": 1, "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""}, {"partNumber": 2, "etag": "\"0cc175b9c0f1b6a831c399e269772661\""}]},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"fileKey": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png",
"readUrl": "https://media.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
이미지
참조 이미지 업로드 완료
PUT 요청의 파트 번호와 ETag를 사용하여 본인 소유의 참조 이미지 업로드를 완료합니다. 저장된 파일 크기를 확인합니다. 반환된 fileKey를 생성 시 참조로 사용하세요.
POST
/
v1
/
actions
/
images_upload_complete
curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_complete' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"b7d73225-716b-45ec-ae43-559cfb3b6412","uploadId":"c547fb7f-f334-46a8-a8bb-80b5b343889a","parts":[{"partNumber":1,"etag":"\"d41d8cd98f00b204e9800998ecf8427e\""},{"partNumber":2,"etag":"\"0cc175b9c0f1b6a831c399e269772661\""}]}'
const input = {
requestId: 'b7d73225-716b-45ec-ae43-559cfb3b6412',
uploadId: 'c547fb7f-f334-46a8-a8bb-80b5b343889a',
parts: [
{
partNumber: 1,
etag: '"d41d8cd98f00b204e9800998ecf8427e"',
},
{
partNumber: 2,
etag: '"0cc175b9c0f1b6a831c399e269772661"',
},
],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_complete', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/images_upload_complete",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412", "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "parts": [{"partNumber": 1, "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""}, {"partNumber": 2, "etag": "\"0cc175b9c0f1b6a831c399e269772661\""}]},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"fileKey": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png",
"readUrl": "https://media.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
PUT 요청의 파트 번호와 ETag를 사용하여 본인 소유의 참조 이미지 업로드를 완료합니다. 저장된 파일 크기를 확인합니다. 반환된 fileKey를 생성 시 참조로 사용하세요.
필요한 권한:
POST https://api.voicecheap.ai/v1/actions/images_upload_complete
인증 및 권한
string
필수
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이
REST 엔드포인트에서는 사용할 수 없습니다.
images: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는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.
{
"type": "object",
"properties": {
"requestId": {
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
"type": "string",
"format": "uuid",
"pattern": "^[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}$"
},
"uploadId": {
"type": "string",
"format": "uuid",
"pattern": "^([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)$",
"description": "The uploadId returned by this domain’s upload_initialize action."
},
"parts": {
"minItems": 1,
"maxItems": 2,
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1,
"maximum": 2
},
"etag": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"required": ["partNumber", "etag"],
"additionalProperties": false
}
}
},
"required": ["uploadId", "parts"],
"additionalProperties": false
}
멱등성
각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요.요청 예제
예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_complete' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"b7d73225-716b-45ec-ae43-559cfb3b6412","uploadId":"c547fb7f-f334-46a8-a8bb-80b5b343889a","parts":[{"partNumber":1,"etag":"\"d41d8cd98f00b204e9800998ecf8427e\""},{"partNumber":2,"etag":"\"0cc175b9c0f1b6a831c399e269772661\""}]}'
const input = {
requestId: 'b7d73225-716b-45ec-ae43-559cfb3b6412',
uploadId: 'c547fb7f-f334-46a8-a8bb-80b5b343889a',
parts: [
{
partNumber: 1,
etag: '"d41d8cd98f00b204e9800998ecf8427e"',
},
{
partNumber: 2,
etag: '"0cc175b9c0f1b6a831c399e269772661"',
},
],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_complete', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/images_upload_complete",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412", "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "parts": [{"partNumber": 1, "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""}, {"partNumber": 2, "etag": "\"0cc175b9c0f1b6a831c399e269772661\""}]},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
응답
성공한 첫 실행은 작업 결과를 data 아래에 포함하여 HTTP 200을 반환합니다. 재전송 시에는 저장된 요청 상태를 대신 반환할 수 있습니다. 예제는 지원되는 응답 중 하나를 보여주며 모든 선택 필드를 포함하지는 않습니다. 완료된 본인 소유 참조 키와 읽기 URL이며, 저장된 바이트 길이가 선언된 파일 크기와 정확히 일치한 후에만 반환됩니다. 생성 인수에는 readUrl이 아닌 fileKey를 사용하세요.{
"data": {
"fileKey": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png",
"readUrl": "https://media.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412"
}
결과 필드
| 필드 | 설명 |
|---|---|
data.fileKey | 생성 참조로 사용할, 소유한 완료 상태 객체의 키입니다. |
data.readUrl | 업로드된 참조 객체의 읽기 URL입니다. 생성 액션은 이 URL이 아닌 fileKey를 받습니다. |
이 요청 복구 및 폴링
연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요.curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"b7d73225-716b-45ec-ae43-559cfb3b6412","operation":"images_upload_complete"}'
HTTP 200
{
"data": {
"requestId": "b7d73225-716b-45ec-ae43-559cfb3b6412",
"operation": "images_upload_complete",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"fileKey": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png",
"readUrl": "https://media.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"
}
}
}
작업 참고 사항
- images:write가 필요하며 추가 업로드 범위는 필요하지 않습니다.
- uploadId는 initialize의 UUID입니다. parts에는 세션에 필요한 1
2개의 파트가 정확히 포함됩니다. 각 파트에는 12의 정수 partNumber와 성공한 PUT 응답에서 가져온 1~256자의 etag 문자열이 있습니다. - 모든 파트 번호가 있어야 하며 중복되지 않아야 합니다. 완료 전에 파트를 정렬하며, ETags는 따옴표로 둘러싼 값으로 정규화됩니다. 스토리지에서 반환한 ETag의 따옴표를 유지해도 됩니다.
- 완료된 객체의 실제 바이트 길이를 fileSize 및 8 MiB 상한과 비교해 확인합니다. 길이가 없거나 일치하지 않거나 상한을 초과하면 객체와 활성 세션을 제거하고 UPLOAD_SIZE_MISMATCH를 반환합니다.
- images_generate에서 fileKey를 referenceImageKey로 전달하세요. 완료된 참조 파일은 동일 사용자가 소유하는 후속 이미지 또는 썸네일 생성에 재사용할 수 있습니다. 생성해도 참조는 소모되지 않습니다.
- 연결된 사용자에게 속한 업로드만 서명, 완료 처리 또는 중단할 수 있습니다. 이 별칭은 다른 업로드 계열을 통해 생성된 세션이더라도 최대 8 MiB의 JPG, PNG 및 WebP 세션만 허용합니다.
- 프로덕션 업로드 세션은 24시간 후에 만료됩니다. 서명된 파트 URL은 한 시간 후에 만료됩니다. 완료와 중단은 활성 세션을 제거하며, 이후 sign-parts와 complete는 Upload not found를 반환합니다. 어느 응답에도 expiresAt 필드는 포함되지 않습니다.
- UUID v4 requestId 또는 HTTP Idempotency-Key 헤더를 사용하고 재시도 시 동일한 입력과 함께 재사용하세요. 통합 계층은 각 변경을 기록하고 다시 실행하지 않은 채 기록된 상태 또는 결과를 반환합니다. failed 또는 interrupted 상태의 요청은 자동으로 재시도되지 않습니다.
- 완료 처리는 멀티파트 세션을 닫습니다. 기록된 결과를 조회하려면 원래 requestId로 완료 처리를 재시도하세요. 닫힌 uploadId에 새 완료 요청을 보내면 Upload not found가 반환됩니다. 이 액션은 참조 보관 만료 시간을 반환하지 않습니다.
사용량
성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.오류
| HTTP 상태 | 코드 | 의미 또는 복구 방법 |
|---|---|---|
| 400 | BAD_REQUEST | 완료 목록에 누락되거나 중복되거나 유효하지 않은 파트 번호가 있습니다. |
| 400 | CREDENTIAL_IN_QUERY | 자격 증명이 access_token 또는 api_key 쿼리 매개변수로 제공되었습니다. 자격 증명은 헤더로 보내세요. |
| 400 | IDEMPOTENCY_CONFLICT | Idempotency-Key 헤더와 본문의 requestId 필드가 일치해야 합니다. |
| 400 | INVALID_REQUEST_ID | requestId 또는 Idempotency-Key가 UUID v4가 아닙니다. |
| 400 | UPLOAD_SIZE_MISMATCH | 완료된 객체의 저장 크기를 확인할 수 없거나, fileSize와 다르거나, 8 MiB를 초과합니다. 객체와 세션이 제거됩니다. |
| 400 | UPLOAD_TYPE_NOT_ALLOWED | 업로드 세션이 지원되는 이미지 유형이 아니거나 8 MiB를 초과합니다. |
| 400 | VALIDATION_ERROR | 인수가 누락되었거나, 지원하지 않는 값이거나, 제한을 초과했거나, 엄격한 입력 스키마에 포함되지 않습니다. |
| 401 | API_KEY_EXPIRED | API 키가 만료되었습니다. |
| 401 | INVALID_API_KEY | 유효하고 만료되지 않은 API 키를 제공하세요. |
| 401 | INVALID_CREDENTIAL | Authorization 헤더의 형식이 잘못되었거나 x-api-key와 충돌합니다. |
| 401 | MISSING_CREDENTIAL | 사용 가능한 헤더 자격 증명이 전달되지 않았거나 4096자를 초과했습니다. |
| 401 | UNAUTHORIZED | 업로드 세션이 다른 사용자에게 속합니다. |
| 401 | USER_NOT_FOUND | 이 자격 증명에 연결된 계정이 더 이상 존재하지 않습니다. |
| 403 | ACCOUNT_UNAVAILABLE | 작업을 수행하는 계정 또는 결제 계정을 사용할 수 없거나 해당 계정이 삭제 중입니다. |
| 403 | AMBIGUOUS_TEAM_API_KEY | 이 자격 증명의 사용자가 둘 이상의 팀에 속해 있어 청구 컨텍스트가 모호합니다. |
| 403 | INSUFFICIENT_SCOPE | 필요한 모든 권한을 부여하거나 다른 자격 증명을 사용하세요. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | 계정의 통합 한도를 확인할 수 없습니다. |
| 403 | SUBSCRIPTION_REQUIRED | 활성 유료 구독을 사용하세요. |
| 403 | TEAM_OWNER_NOT_FOUND | 실제로 적용되는 팀 소유자 계정을 찾을 수 없습니다. |
| 404 | NOT_FOUND | 업로드 세션을 알 수 없거나, 만료되었거나, 이미 완료되었거나, 중단되었습니다. |
| 409 | CONCURRENT_ACTION_LIMIT_REACHED | 이 계정에서는 이미 10개의 연동 액션이 실행 중입니다. 새 액션을 시작하기 전에 기존 요청을 폴링하세요. |
| 409 | IDEMPOTENCY_CONFLICT | 이 요청 식별자는 이미 다른 인수와 함께 사용되었습니다. 헤더와 본문의 식별자가 일치하지 않으면 동일한 코드와 함께 HTTP 400을 반환합니다. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | 월간 한도가 초기화될 때까지 기다리거나 요금제를 변경하세요. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Retry-After가 있으면 지정된 시간만큼 기다리고 백오프를 적용하세요. |
| 500 | INTERNAL_ERROR | 변경 작업을 재시도하기로 결정하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요. |
| 503 | ACTION_RESULT_UNAVAILABLE | 액션은 실행되었지만 결과를 저장할 수 없습니다. 새 생성을 시작하기 전에 저장된 요청 상태와 리소스 기록을 확인하세요. |
| 503 | INTERNAL_ERROR | 활성 업로드 세션을 읽을 수 없습니다. 완료 처리를 다시 시도하기 전에 요청 상태를 확인하세요. |
| 503 | SERVER_RESTARTING | 서버가 다시 시작 중입니다. 잠시 후 재시도하고, 변경 작업의 경우 동일한 요청 식별자를 유지하세요. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["images:write"]
}
}
이 페이지가 도움이 되었나요?