curl --request POST 'https://api.voicecheap.ai/v1/actions/segments_text_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","segmentIndex":0,"requestId":"41321bda-e243-4b6f-96a4-622cd047c991","source":"original","text":"Bienvenue au lancement de VoiceCheap."}'
const input = {
projectId: 'project_launch_2026',
segmentIndex: 0,
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
source: 'original',
text: 'Bienvenue au lancement de VoiceCheap.',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/segments_text_update', {
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/segments_text_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "segmentIndex": 0, "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "source": "original", "text": "Bienvenue au lancement de VoiceCheap."},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"status": "queued",
"jobId": "41321bda-e243-4b6f-96a4-622cd047c991",
"queue": {
"projectId": "project_launch_2026",
"revision": 1,
"items": [
{
"id": "41321bda-e243-4b6f-96a4-622cd047c991",
"action": {
"type": "text",
"segmentIndex": 0,
"source": "original"
},
"status": "queued",
"createdAt": 1792152000000
}
]
}
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
Transkrypcje i edycja
Edytuj segment transkrypcji
Dodaj do kolejki edycję tekstu oryginału lub tłumaczenia. requestId musi być stałym UUID przy ponawianiu żądania. Sprawdzaj zakończenie przez segment_actions_list.
POST
/
v1
/
actions
/
segments_text_update
curl --request POST 'https://api.voicecheap.ai/v1/actions/segments_text_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","segmentIndex":0,"requestId":"41321bda-e243-4b6f-96a4-622cd047c991","source":"original","text":"Bienvenue au lancement de VoiceCheap."}'
const input = {
projectId: 'project_launch_2026',
segmentIndex: 0,
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
source: 'original',
text: 'Bienvenue au lancement de VoiceCheap.',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/segments_text_update', {
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/segments_text_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "segmentIndex": 0, "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "source": "original", "text": "Bienvenue au lancement de VoiceCheap."},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"status": "queued",
"jobId": "41321bda-e243-4b6f-96a4-622cd047c991",
"queue": {
"projectId": "project_launch_2026",
"revision": 1,
"items": [
{
"id": "41321bda-e243-4b6f-96a4-622cd047c991",
"action": {
"type": "text",
"segmentIndex": 0,
"source": "original"
},
"status": "queued",
"createdAt": 1792152000000
}
]
}
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
Dodaj do kolejki edycję tekstu oryginału lub tłumaczenia. requestId musi być stałym UUID przy ponawianiu żądania. Sprawdzaj zakończenie przez segment_actions_list.
Wymagane uprawnienia:
POST https://api.voicecheap.ai/v1/actions/segments_text_update
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.
transcription: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
wymagane
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec:
^[^/\\]+$.integer
wymagane
Liczba całkowita.Minimum: 0. Maksimum: 9007199254740991.
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
Wartość tekstowa.Dozwolone wartości: “original”, “translated”.
string
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 200. Wzorzec:
^[^/\\]+$.string
wymagane
Wartość tekstowa.Maksymalna długość: 3000.
boolean
Wartość logiczna.
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": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"segmentIndex": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"requestId": {
"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}$",
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries."
},
"source": {
"type": "string",
"enum": ["original", "translated"]
},
"workId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"text": {
"type": "string",
"maxLength": 3000
},
"enableEditing": {
"type": "boolean"
}
},
"required": ["projectId", "segmentIndex", "source", "text"],
"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/segments_text_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","segmentIndex":0,"requestId":"41321bda-e243-4b6f-96a4-622cd047c991","source":"original","text":"Bienvenue au lancement de VoiceCheap."}'
const input = {
projectId: 'project_launch_2026',
segmentIndex: 0,
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
source: 'original',
text: 'Bienvenue au lancement de VoiceCheap.',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/segments_text_update', {
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/segments_text_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "segmentIndex": 0, "requestId": "41321bda-e243-4b6f-96a4-622cd047c991", "source": "original", "text": "Bienvenue au lancement de VoiceCheap."},
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. Zwraca potwierdzenie przyjęcia do kolejki wraz z aktualną migawką kolejki dla edycji tekstu oryginalnego lub przetłumaczonego.{
"data": {
"status": "queued",
"jobId": "41321bda-e243-4b6f-96a4-622cd047c991",
"queue": {
"projectId": "project_launch_2026",
"revision": 1,
"items": [
{
"id": "41321bda-e243-4b6f-96a4-622cd047c991",
"action": {
"type": "text",
"segmentIndex": 0,
"source": "original"
},
"status": "queued",
"createdAt": 1792152000000
}
]
}
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
Pola wyniku
| Pole | Opis |
|---|---|
data.status | started, gdy to zadanie zostało przejęte do wykonania lub rozpoczęte; w przeciwnym razie queued. Żadna z tych wartości nie oznacza ukończenia. |
data.jobId | Identyfikator zadania kolejki, równy stałemu requestId zgłoszenia. |
data.queue | Aktualna migawka kolejki projektu, która może już wskazywać, że zadanie trwa lub osiągnęło stan końcowy. |
data.queue.projectId | Identyfikator projektu nadrzędnego. |
data.queue.revision | Rewizja migawki kolejki. Jest niezależna od projects_get.segmentStructureRevision. |
data.queue.items | Postęp działań projektu: identyfikatory zadań, metadane działań, stan, znaczniki czasu i opcjonalny publiczny errorCode. |
data.queue.items[].id | Identyfikator zadania; jest równy requestId pierwotnego zgłoszenia do kolejki. |
data.queue.items[].action | Tylko metadane działania: type, segmentIndex oraz opcjonalnie workId, translatedVersionId i source. Przesłany tekst, wartości czasu i instrukcje ponownego generowania nie są zwracane. |
data.queue.items[].status | queued, running, completed, failed lub cancelled. |
data.queue.items[].createdAt | Czas utworzenia elementu kolejki w milisekundach czasu Unix. |
data.queue.items[].startedAt | Opcjonalny czas pierwszego uruchomienia w milisekundach Unix. |
data.queue.items[].finishedAt | Opcjonalny czas osiągnięcia stanu końcowego w milisekundach Unix. |
data.queue.items[].errorCode | Opcjonalny publiczny kod błędu. Niesklasyfikowane błędy używają ACTION_FAILED. |
data.queue.items[].seenAt | Opcjonalny czas potwierdzenia wyłącznie dla uwierzytelnionego odbiorcy. |
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":"41321bda-e243-4b6f-96a4-622cd047c991","operation":"segments_text_update"}'
HTTP 200
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "segments_text_update",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"status": "queued",
"jobId": "41321bda-e243-4b6f-96a4-622cd047c991",
"queue": {
"projectId": "project_launch_2026",
"revision": 1,
"items": [
{
"id": "41321bda-e243-4b6f-96a4-622cd047c991",
"action": {
"type": "text",
"segmentIndex": 0,
"source": "original"
},
"status": "queued",
"createdAt": 1792152000000
}
]
}
}
}
}
Uwagi do operacji
- Użyj jednego requestId w formacie UUID v4 dla zamierzonej edycji i używaj go ponownie z identycznymi argumentami przy ponawianiu żądania. jobId jest równy temu requestId.
- Przyjęcie do realizacji zwraca started lub queued, a nie potwierdzenie ukończenia. Sprawdzaj stan przez segment_actions_list i szukaj items[].id równego jobId aż do uzyskania completed, failed lub cancelled, a następnie odśwież dane przez transcripts_get i projects_get.
- queue.revision śledzi stan kolejki; nie jest rewizją struktury segmentów źródłowych. Akcje kolejkowe rejestrują bieżącą strukturę w chwili przyjęcia do realizacji. Późniejsza niezgodna zmiana struktury może spowodować błąd elementu z kodem SEGMENT_STRUCTURE_CHANGED.
- Przyjmowana jest tylko jedna oczekująca akcja dla tego samego logicznego celu segmentu. Nowy requestId nie omija SEGMENT_ACTION_ALREADY_PENDING.
- Błędy wykonania w kolejce są widoczne jako items[].status o wartości failed wraz z errorCode i nie zmieniają wyniku pomyślnego zgłoszenia.
- Przy edycji oryginału pomiń workId i enableEditing. Edycja tekstu oryginalnego oznacza dany segment jako oczekujący na tłumaczenie we wszystkich wersjach językowych; nie generuje automatycznie nowej mowy.
- Przy edycji tłumaczeń użyj source o wartości translated i podaj workId. Wymagane są oba uprawnienia: transcription:write i translations:write.
- enableEditing jest dozwolone tylko przy edycji tłumaczeń i jawnie przełącza tryb ręcznego tłumaczenia. Edycja tłumaczenia aktualizuje tekst i stan edycji bez ponownego generowania mowy.
- Schemat akcji dopuszcza pusty ciąg tekstowy. Użyj dedykowanej akcji segments_delete, aby usunąć segment i zachować zgodność wszystkich języków.
- Odpowiedzi kolejki, również przy przesyłaniu, anulowaniu, odpytywaniu i ponawianiu, zawierają tylko metadane działań. Odczytuj treść transkrypcji przez transcripts_get z wymaganym uprawnieniem transcription:read.
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 | Indeks segmentu źródłowego nie istnieje lub argumenty kolejki są nieprawidłowe. |
| 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 | Podaj requestId lub Idempotency-Key w formacie UUID v4. |
| 400 | SEGMENT_QUEUE_FULL | Projekt ma już 50 oczekujących akcji segmentów. |
| 400 | VALIDATION_ERROR | Popraw dane wejściowe zgodnie ze schematem. Nieprawidłowe lub niespójne wartości są odrzucane przed wykonaniem. |
| 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 | FORBIDDEN | Uwierzytelniony podmiot wykonujący akcję nie ma dostępu do tego projektu. |
| 403 | INSUFFICIENT_SCOPE | Edycja przetłumaczonego tekstu dodatkowo wymaga translations:write. |
| 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 | PROJECT_NOT_FOUND | Projekt nie istnieje na dostępnym koncie. |
| 404 | TRANSLATION_NOT_FOUND | Edytowana przetłumaczona wersja językowa nie należy do tego projektu. |
| 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 | Używaj ponownie identyfikatora wyłącznie z tą samą operacją i tymi samymi argumentami. |
| 409 | SEGMENT_ACTION_ALREADY_PENDING | Akcja dla tego samego logicznego segmentu docelowego jest już w kolejce lub w trakcie wykonywania. |
| 409 | SEGMENT_STRUCTURE_BUSY | Trwa modyfikacja struktury segmentów; przed ponownym przesłaniem przeładuj projekt. |
| 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 | Kolejka segmentów jest wyłączona na serwerze deweloperskim; akcja nie została przyjęta do realizacji. |
| 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": ["transcription:write"]
}
}
Czy ta strona była pomocna?

