> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Rozpocznij przesyłanie obrazu referencyjnego > Przygotuj przesyłanie obrazu referencyjnego JPG, PNG lub WebP o rozmiarze do 8 MiB. Użyj images_upload_sign_parts, aby uzyskać adresy URL PUT, prześlij dane, a następnie wywołaj images_upload_complete i użyj jego fileKey podczas generowania. Przygotuj przesyłanie obrazu referencyjnego JPG, PNG lub WebP o rozmiarze do 8 MiB. Użyj images\_upload\_sign\_parts, aby uzyskać adresy URL PUT, prześlij dane, a następnie wywołaj images\_upload\_complete i użyj jego fileKey podczas generowania. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/images_upload_initialize ``` ## Uwierzytelnianie i uprawnienia 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. Wymagane uprawnienia: `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 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}$`. Nazwa pliku obrazu z rozszerzeniem odpowiadającym contentType. Minimalna długość: 1. Maksymalna długość: 250. Wzorzec: `\.(?:jpe?g|png|webp)$`. Wartość tekstowa. Dozwolone wartości: "image/jpeg", "image/png", "image/webp". Dokładny rozmiar pliku w bajtach, do 8 MiB. Minimum: 1. Maksimum: 8388608. 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. ```json theme={null} { "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}$" }, "filename": { "type": "string", "minLength": 1, "maxLength": 250, "pattern": "\\.(?:jpe?g|png|webp)$", "description": "The image filename, with an extension matching contentType." }, "contentType": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"] }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 8388608, "description": "Exact file size in bytes, up to 8 MiB." } }, "required": ["filename", "contentType", "fileSize"], "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. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/images_upload_initialize' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"85d80887-5e1c-4a86-bbad-bb105487f7e4","filename":"reference.png","contentType":"image/png","fileSize":7340032}' ``` ```javascript JavaScript theme={null} const input = { requestId: '85d80887-5e1c-4a86-bbad-bb105487f7e4', filename: 'reference.png', contentType: 'image/png', fileSize: 7340032, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/images_upload_initialize', { 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); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.voicecheap.ai/v1/actions/images_upload_initialize", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "filename": "reference.png", "contentType": "image/png", "fileSize": 7340032}, 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. Nowa sesja wieloczęściowego przesyłania obrazu referencyjnego, przyszły klucz obiektu, rozmiar części w bajtach i maksymalna liczba równoległych przesyłań. Nie przesyła to żadnych bajtów obrazu ani nie przygotowuje key do generowania. ```json HTTP 200 theme={null} { "data": { "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "key": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png", "partSize": 5242880, "maxConcurrency": 4 }, "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "operation": "images_upload_initialize", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "operation": "images_upload_initialize", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." }, "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4" } ``` ## Pola wyniku | Pole | Opis | | - | - | | `data.uploadId` | UUID identyfikujący aktywną sesję przesyłania. Przekazuj go do pozostałych akcji przesyłania. | | `data.key` | Przyszły klucz obiektu należącego do użytkownika. Użyj fileKey z pomyślnego zakończenia przesyłania jako odwołania do generowania. | | `data.partSize` | Wymagany rozmiar części w bajtach, z wyjątkiem ostatniej części, która zawiera pozostałe bajty. | | `data.maxConcurrency` | Maksymalna sugerowana liczba równolegle przesyłanych części: 4. | ## 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. ```bash theme={null} 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":"85d80887-5e1c-4a86-bbad-bb105487f7e4","operation":"images_upload_initialize"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "85d80887-5e1c-4a86-bbad-bb105487f7e4", "operation": "images_upload_initialize", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "uploadId": "c547fb7f-f334-46a8-a8bb-80b5b343889a", "key": "uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png", "partSize": 5242880, "maxConcurrency": 4 } } } ``` ## Uwagi do operacji * Wymaga images:write; dodatkowy zakres przesyłania nie jest potrzebny. * Z filename usuwane są skrajne białe znaki; musi zawierać 1–250 znaków i kończyć się na .jpg, .jpeg, .png lub .webp. Rozszerzenie musi odpowiadać contentType: image/jpeg, image/png lub image/webp. fileSize to dokładna całkowita liczba bajtów, od 1 do 8,388,608. * Wspólna implementacja przesyłania zwraca partSize równe 5 MiB (5,242,880 bajtów) dla tych obrazów referencyjnych. Plik o rozmiarze najwyżej 5 MiB używa jednej części; większy plik o rozmiarze do 8 MiB używa dwóch. Uzyskaj adresy URL PUT przez images\_upload\_sign\_parts, prześlij bajty, a następnie wywołaj images\_upload\_complete. * Użyj fileKey zwróconego po ukończeniu jako referenceImageKey w images\_generate. Wynik initialize używa key, a nie fileKey. Nie przekazuj key do generowania przed ukończeniem. * 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. * Ta akcja korzysta z własnych utworzonych materiałów i przesłanych plików połączonego użytkownika, również gdy dane uwierzytelniające są połączone w kontekście zespołu. * 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. * Nazwa pliku w kluczu obiektu jest oczyszczana i może zostać skrócona. Zachowaj dokładnie zwrócone key i uploadId; nie twórz ich samodzielnie. Bajty obrazu są weryfikowane podczas generowania, a zadeklarowany rozmiar i typ — podczas przesyłania. ## 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 | `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 | `REFERENCE_IMAGE_INVALID` | Rozszerzenie nazwy pliku nie odpowiada zadeklarowanemu contentType obrazu. | | 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 | `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. | | 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ę utworzyć lub zapisać sesji przesyłania. Ponów żądanie 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. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["images:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.