curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_sign_parts' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"8d16d4dc-a1a1-45bc-8f9c-75612ea7561f","uploadId":"c547fb7f-f334-46a8-a8bb-80b5b343889a","partNumbers":[1,2]}'
const input = {
requestId: '8d16d4dc-a1a1-45bc-8f9c-75612ea7561f',
uploadId: 'c547fb7f-f334-46a8-a8bb-80b5b343889a',
partNumbers: [1, 2],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_sign_parts', {
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_sign_parts",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f", "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "partNumbers": [1, 2]},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"presignedUrls": [
{
"partNumber": 1,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=1&uploadId=example-upload&signature=example-signature"
},
{
"partNumber": 2,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=2&uploadId=example-upload&signature=example-signature"
}
]
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
Obrazy
Pobierz adresy przesyłania obrazu referencyjnego
Pobierz podpisane adresy URL PUT dla należącego do Ciebie przesyłania obrazu referencyjnego. Obraz o rozmiarze 8 MiB ma najwyżej dwie części. Zapisz ETag zwrócony przez każde PUT do użycia w upload_complete.
POST
/
v1
/
actions
/
images_upload_sign_parts
curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_sign_parts' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"8d16d4dc-a1a1-45bc-8f9c-75612ea7561f","uploadId":"c547fb7f-f334-46a8-a8bb-80b5b343889a","partNumbers":[1,2]}'
const input = {
requestId: '8d16d4dc-a1a1-45bc-8f9c-75612ea7561f',
uploadId: 'c547fb7f-f334-46a8-a8bb-80b5b343889a',
partNumbers: [1, 2],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_sign_parts', {
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_sign_parts",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f", "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "partNumbers": [1, 2]},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"presignedUrls": [
{
"partNumber": 1,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=1&uploadId=example-upload&signature=example-signature"
},
{
"partNumber": 2,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=2&uploadId=example-upload&signature=example-signature"
}
]
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
Pobierz podpisane adresy URL PUT dla należącego do Ciebie przesyłania obrazu referencyjnego. Obraz o rozmiarze 8 MiB ma najwyżej dwie części. Zapisz ETag zwrócony przez każde PUT do użycia w upload_complete.
Wymagane uprawnienia:
POST https://api.voicecheap.ai/v1/actions/images_upload_sign_parts
Uwierzytelnianie i uprawnienia
string
wymagane
Wyślij klucz API VoiceCheap w tym nagłówku. Obsługiwany jest również nagłówek Authorization: Bearer z tym samym kluczem API. Tokeny dostępu OAuth są
akceptowane tylko przez MCP, a nie przez ten endpoint REST.
images:write.
Wymagana jest aktywna płatna subskrypcja. Uprawnienia nie zmieniają ról w zespole, własności zasobów, kredytów na multimedia ani limitów planu.
Parametry
string
Opcjonalne na poziomie transportu: jeśli identyfikator zostanie pominięty, serwer doda go przed walidacją. Podaj własny, stały UUID v4, aby bezpiecznie odzyskać wynik po utracie odpowiedzi.Format: “uuid”. Wzorzec:
^[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
wymagane
uploadId zwrócony przez akcję upload_initialize tej domeny.Format: “uuid”. Wzorzec:
^([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
wymagane
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Minimalna liczba elementów: 1. Maksymalna liczba elementów: 2.
Pełny schemat danych wejściowych
Pełny schemat danych wejściowych
Poniższy JSON Schema zachowuje dokładne nazwy pól, typy zagnieżdżone, wartości domyślne, ograniczenia i akceptowane wartości udostępniane przez mechanizm wykrywania. Dodatkowe reguły zależności między polami znajdują się w uwagach do operacji.
{
"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."
},
"partNumbers": {
"minItems": 1,
"maxItems": 2,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 2
}
}
},
"required": ["uploadId", "partNumbers"],
"additionalProperties": false
}
Idempotencja
Dla każdej operacji zmieniającej dane użyj UUID v4 w requestId lub w nagłówku HTTP Idempotency-Key. Po awarii sieci użyj ponownie tego samego identyfikatora i identycznych argumentów. Jeśli podasz oba, muszą być zgodne. Ponowienie zapisanego żądania nie powtarza operacji ani nie zużywa kolejnego wywołania z miesięcznego limitu. Żądania zakończone błędem lub przerwane nie są automatycznie uruchamiane ponownie. Każda operacja zmieniająca dane może zwrócić HTTP 202, gdy ponowienie napotka to samo żądanie nadal w stanie running, nawet jeśli jej pierwsze wykonanie zwykle jest synchroniczne. Jeśli wykonanie się zakończyło, ale resultStored ma wartość false, ponowienie zwraca HTTP 200 z zapisanym stanem żądania zamiast pierwotnego wyniku. Pobierz wynik za pomocą akcji historii, wyniku lub pobierania właściwej dla danej domeny.Przykłady żądań
Zastąp przykładowe identyfikatory zasobów i klucze multimediów wartościami zwróconymi dla Twojego konta. Przy ponawianiu tej samej operacji zmieniającej dane zachowaj identyfikator żądania.curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_sign_parts' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"8d16d4dc-a1a1-45bc-8f9c-75612ea7561f","uploadId":"c547fb7f-f334-46a8-a8bb-80b5b343889a","partNumbers":[1,2]}'
const input = {
requestId: '8d16d4dc-a1a1-45bc-8f9c-75612ea7561f',
uploadId: 'c547fb7f-f334-46a8-a8bb-80b5b343889a',
partNumbers: [1, 2],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_sign_parts', {
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_sign_parts",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f", "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "partNumbers": [1, 2]},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
Odpowiedź
Pierwsze pomyślne wykonanie zwraca HTTP 200 z wynikiem operacji w data. Ponowienie może zamiast tego zwrócić zapisany stan żądania. Przykład przedstawia jedną obsługiwaną odpowiedź, bez wszystkich opcjonalnych pól. Tablica tymczasowych podpisanych adresów URL PUT, po jednym dla każdego unikalnego żądanego numeru części. Odpowiedź nie zawiera bajtów obrazu, wartości ETags ani pól rozmiaru poszczególnych części.{
"data": {
"presignedUrls": [
{
"partNumber": 1,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=1&uploadId=example-upload&signature=example-signature"
},
{
"partNumber": 2,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=2&uploadId=example-upload&signature=example-signature"
}
]
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f"
}
Pola wyniku
| Pole | Opis |
|---|---|
data.presignedUrls | Tablica podpisanych miejsc docelowych przesyłania części. |
data.presignedUrls[].partNumber | Numer części dla tego adresu URL, liczony od jednego. |
data.presignedUrls[].url | Tymczasowy adres URL PUT ważny przez jedną godzinę; użyj dokładnej podpisanej wartości Content-Length dla tej części. |
Odzyskaj żądanie i sprawdź jego stan
Używaj tego samego identyfikatora także po utracie połączenia. Jeśli resultStored ma wartość false, pobierz wynik za pomocą odpowiedniej akcji historii, wyniku lub pobierania. Nigdy nie uruchamiaj drugiego generowania tylko po to, aby sprawdzić postęp.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":"8d16d4dc-a1a1-45bc-8f9c-75612ea7561f","operation":"images_upload_sign_parts"}'
HTTP 200
{
"data": {
"requestId": "8d16d4dc-a1a1-45bc-8f9c-75612ea7561f",
"operation": "images_upload_sign_parts",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"presignedUrls": [
{
"partNumber": 1,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=1&uploadId=example-upload&signature=example-signature"
},
{
"partNumber": 2,
"url": "https://uploads.example.com/uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png?partNumber=2&uploadId=example-upload&signature=example-signature"
}
]
}
}
}
Uwagi do operacji
- Wymaga images:write; dodatkowy zakres przesyłania nie jest potrzebny.
- uploadId to UUID z initialize. partNumbers zawiera 1–2 liczby całkowite, każdą w zakresie od 1 do 2, a każda część musi istnieć dla zadeklarowanego fileSize tej sesji. Zduplikowane żądane numery części są scalane do jednego adresu URL.
- Wyślij surowe bajty binarne każdej części metodą PUT na odpowiedni zwrócony adres URL. Content-Length jest objęty podpisem i musi być dokładnie równy min(partSize, fileSize - (partNumber - 1) × partSize). W przykładzie dla 7 MiB część 1 ma 5,242,880 bajtów, a część 2 ma 2,097,152 bajtów. Nie wysyłaj JSON, multipart/form-data ani base64 na podpisany adres URL.
- Zapisz nagłówek odpowiedzi ETag z każdego udanego PUT i prześlij te wartości do images_upload_complete. Traktuj podpisane adresy URL jako prywatne, tymczasowe uprawnienia do przesyłania.
- Tylko przesłany plik należący do połączonego użytkownika może zostać podpisany, ukończony lub przerwany. Te aliasy akceptują tylko sesje JPG, PNG i WebP o rozmiarze maksymalnie 8 MiB, nawet jeśli sesja została utworzona przez inną rodzinę przesyłania.
- Produkcyjna sesja przesyłania wygasa po 24 godzinach. Podpisane adresy URL części wygasają po jednej godzinie. Zakończenie i przerwanie przesyłania usuwa aktywną sesję; sign-parts i complete zwracają wtedy Upload not found. Żadna z tych odpowiedzi nie zawiera pola expiresAt.
- Użyj requestId w formacie UUID v4 lub nagłówka HTTP Idempotency-Key i używaj tej samej wartości z identycznymi danymi wejściowymi przy ponownych próbach. Warstwa integracji zapisuje każdą modyfikację i zwraca jej zapisany stan lub wynik bez ponownego wykonywania. Żądanie w stanie failed lub interrupted nie jest automatycznie ponawiane.
- Aby uzyskać nowe adresy URL po ich wygaśnięciu po jednej godzinie, gdy sesja jest nadal aktywna, wywołaj sign-parts z nowym requestId. Ponowienie z tym samym requestId zwraca zapisany wynik, w tym stare adresy URL.
Wykorzystanie
Każde pomyślne wywołanie zużywa jedno wywołanie z miesięcznego limitu API/MCP. Obowiązują również kredyty na multimedia oraz limity generowania danej operacji.Błędy
| Status HTTP | Kod | Znaczenie lub sposób rozwiązania |
|---|---|---|
| 400 | BAD_REQUEST | Numer części nie istnieje dla zadeklarowanego rozmiaru pliku. |
| 400 | CREDENTIAL_IN_QUERY | Dane uwierzytelniające zostały podane w parametrze zapytania access_token lub api_key. Wysyłaj dane uwierzytelniające w nagłówkach. |
| 400 | IDEMPOTENCY_CONFLICT | Nagłówek Idempotency-Key i pole requestId w treści żądania muszą być zgodne. |
| 400 | INVALID_REQUEST_ID | requestId lub Idempotency-Key nie jest identyfikatorem UUID v4. |
| 400 | UPLOAD_TYPE_NOT_ALLOWED | Sesja przesyłania nie dotyczy obsługiwanego typu obrazu lub przekracza 8 MiB. |
| 400 | VALIDATION_ERROR | Brakuje argumentu, ma on nieobsługiwaną wartość, przekracza limit lub nie należy do ścisłego schematu danych wejściowych. |
| 401 | API_KEY_EXPIRED | Klucz API wygasł. |
| 401 | INVALID_API_KEY | Podaj prawidłowy, niewygasły klucz API. |
| 401 | INVALID_CREDENTIAL | Nagłówek Authorization ma nieprawidłowy format lub jest sprzeczny z x-api-key. |
| 401 | MISSING_CREDENTIAL | Nie podano użytecznych danych uwierzytelniających w nagłówku lub przekroczyły one 4096 znaków. |
| 401 | UNAUTHORIZED | Sesja przesyłania należy do innego użytkownika. |
| 401 | USER_NOT_FOUND | Konto powiązane z poświadczeniem już nie istnieje. |
| 403 | ACCOUNT_UNAVAILABLE | Konto wykonujące operację lub konto rozliczeniowe jest niedostępne albo jest w trakcie usuwania. |
| 403 | AMBIGUOUS_TEAM_API_KEY | Użytkownik, do którego należą dane uwierzytelniające, należy do więcej niż jednego zespołu, więc kontekst rozliczeniowy jest niejednoznaczny. |
| 403 | INSUFFICIENT_SCOPE | Nadaj wszystkie wymagane uprawnienia lub wybierz inne dane uwierzytelniające. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | Nie udało się zweryfikować limitów integracji konta. |
| 403 | SUBSCRIPTION_REQUIRED | Użyj aktywnej płatnej subskrypcji. |
| 403 | TEAM_OWNER_NOT_FOUND | Nie znaleziono konta faktycznego właściciela zespołu. |
| 404 | NOT_FOUND | Sesja przesyłania jest nieznana, wygasła, została ukończona lub przerwana. |
| 409 | CONCURRENT_ACTION_LIMIT_REACHED | Na tym koncie działa już 10 akcji integracji. Sprawdzaj stan istniejącego żądania przed rozpoczęciem kolejnego. |
| 409 | IDEMPOTENCY_CONFLICT | Identyfikator żądania został już użyty z innymi argumentami; niezgodność identyfikatorów w nagłówku i treści zwraca HTTP 400 z tym samym kodem. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Poczekaj na odnowienie miesięcznego limitu lub zmień plan. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Jeśli występuje nagłówek Retry-After, odczekaj wskazany czas i stosuj rosnące odstępy między ponowieniami. |
| 500 | INTERNAL_ERROR | Sprawdź stan zapisanego żądania i historię zasobu przed podjęciem decyzji o ponowieniu operacji zmieniającej dane. |
| 503 | ACTION_RESULT_UNAVAILABLE | Akcja została wykonana, ale nie udało się zapisać jej wyniku. Sprawdź zapisany stan żądania i historię zasobu przed rozpoczęciem nowego generowania. |
| 503 | INTERNAL_ERROR | Nie udało się odczytać aktywnej sesji przesyłania. Ponów z tym samym identyfikatorem mutacji i sprawdź jej zapisany stan. |
| 503 | SERVER_RESTARTING | Serwer jest uruchamiany ponownie. Spróbuj ponownie wkrótce i zachowaj ten sam identyfikator żądania dla operacji zmieniającej dane. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["images:write"]
}
}
Czy ta strona była pomocna?

