curl --request POST 'https://api.voicecheap.ai/v1/actions/settings_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"58d5bb53-00d0-4692-bdaf-c6650ee87e30","brandVocabulary":["VoiceCheap"],"customTranslationInstructions":"Keep product names unchanged.","isSoundNotificationsEnabled":true}'
const input = {
requestId: '58d5bb53-00d0-4692-bdaf-c6650ee87e30',
brandVocabulary: ['VoiceCheap'],
customTranslationInstructions: 'Keep product names unchanged.',
isSoundNotificationsEnabled: true,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/settings_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/settings_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30", "brandVocabulary": ["VoiceCheap"], "customTranslationInstructions": "Keep product names unchanged.", "isSoundNotificationsEnabled": True},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"updated": true
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
Ustawienia i powiadomienia
Zaktualizuj ustawienia konta
Zaktualizuj obsługiwane ustawienia osobiste. Tylko właściciel zespołu może zmieniać wspólne słownictwo i instrukcje tłumaczenia. Pominięte ustawienia pozostają bez zmian.
POST
/
v1
/
actions
/
settings_update
curl --request POST 'https://api.voicecheap.ai/v1/actions/settings_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"58d5bb53-00d0-4692-bdaf-c6650ee87e30","brandVocabulary":["VoiceCheap"],"customTranslationInstructions":"Keep product names unchanged.","isSoundNotificationsEnabled":true}'
const input = {
requestId: '58d5bb53-00d0-4692-bdaf-c6650ee87e30',
brandVocabulary: ['VoiceCheap'],
customTranslationInstructions: 'Keep product names unchanged.',
isSoundNotificationsEnabled: true,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/settings_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/settings_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30", "brandVocabulary": ["VoiceCheap"], "customTranslationInstructions": "Keep product names unchanged.", "isSoundNotificationsEnabled": True},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"updated": true
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
Zaktualizuj obsługiwane ustawienia osobiste. Tylko właściciel zespołu może zmieniać wspólne słownictwo i instrukcje tłumaczenia. Pominięte ustawienia pozostają bez zmian.
Wymagane uprawnienia:
POST https://api.voicecheap.ai/v1/actions/settings_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.
settings: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
Wartość tekstowa.Minimalna długość: 1. Maksymalna długość: 120.
array
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Maksymalna liczba elementów: 1000.
string
Wartość tekstowa.Maksymalna długość: 500.
union
Akceptuje warianty wymienione w pełnym schemacie danych wejściowych.
array
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Maksymalna liczba elementów: 50.
array
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Maksymalna liczba elementów: 50.
array
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Maksymalna liczba elementów: 10.
object
Obiekt JSON. Pola zagnieżdżone opisuje pełny schemat danych wejściowych.
boolean
Wartość logiczna.
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": {
"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."
},
"companyName": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"brandVocabulary": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"maxLength": 500
}
},
"customTranslationInstructions": {
"type": "string",
"maxLength": 500
},
"favoriteTemplates": {
"anyOf": [
{
"type": "object",
"properties": {
"dynamicSubtitles": {
"anyOf": [
{
"type": "string",
"enum": [
"Sara",
"Daniel",
"Dan 2",
"Hormozi 4",
"Dan",
"Devin",
"Tayo",
"Ella",
"Tracy",
"Luke",
"Hormozi 1",
"Hormozi 2",
"Hormozi 3",
"Hormozi 5",
"Leon",
"Ali",
"Beast",
"Maya",
"Karl",
"Iman",
"Umi",
"David",
"Noah",
"Gstaad",
"Malta",
"Nema",
"Seth",
"William"
]
},
{
"type": "null"
}
]
},
"voiceIds": {
"anyOf": [
{
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"targetLanguagePresets": {
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"languages": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 64
}
}
},
"required": ["id", "name", "languages"],
"additionalProperties": false
}
},
"socialMediaStatsPresets": {
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"channelIds": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/]+$"
}
}
},
"required": ["id", "name", "channelIds"],
"additionalProperties": false
}
},
"textToSpeechBrandPresets": {
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"voice": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"instructionPreset": {
"type": "string",
"enum": ["default", "cheerful", "calm", "narrator", "dramatic", "whisper", "energetic"]
},
"instructions": {
"type": "string",
"maxLength": 300
},
"speed": {
"type": "number",
"minimum": 0.5,
"maximum": 2
}
},
"required": ["id", "name", "voice", "instructionPreset", "instructions", "speed"],
"additionalProperties": false
}
},
"defaultVoiceCloningSettings": {
"type": "object",
"properties": {
"stability": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"similarity": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": ["stability", "similarity"],
"additionalProperties": false
},
"isSoundNotificationsEnabled": {
"type": "boolean"
},
"isVoiceCloningSettingsTipDismissed": {
"type": "boolean"
}
},
"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/settings_update' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"58d5bb53-00d0-4692-bdaf-c6650ee87e30","brandVocabulary":["VoiceCheap"],"customTranslationInstructions":"Keep product names unchanged.","isSoundNotificationsEnabled":true}'
const input = {
requestId: '58d5bb53-00d0-4692-bdaf-c6650ee87e30',
brandVocabulary: ['VoiceCheap'],
customTranslationInstructions: 'Keep product names unchanged.',
isSoundNotificationsEnabled: true,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/settings_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/settings_update",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30", "brandVocabulary": ["VoiceCheap"], "customTranslationInstructions": "Keep product names unchanged.", "isSoundNotificationsEnabled": True},
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. Potwierdza zapisanie podanych obsługiwanych ustawień.{
"data": {
"updated": true
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30"
}
Pola wyniku
| Pole | Opis |
|---|---|
data.updated | true po zakończeniu aktualizacji ustawień. |
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":"58d5bb53-00d0-4692-bdaf-c6650ee87e30","operation":"settings_update"}'
HTTP 200
{
"data": {
"requestId": "58d5bb53-00d0-4692-bdaf-c6650ee87e30",
"operation": "settings_update",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"updated": true
}
}
}
Uwagi do operacji
- Podaj co najmniej jedno ustawienie poza opcjonalnym requestId. Pominięte ustawienia pozostają bez zmian.
- Tylko właściciel zespołu może zmieniać brandVocabulary i customTranslationInstructions. Członkowie zespołu mogą aktualizować pozostałe własne preferencje.
- Słownik przyjmuje do 1,000 terminów. Każdy znormalizowany termin może zawierać co najwyżej 49 znaków i co najwyżej pięć słów, bez nawiasów kwadratowych, klamrowych, ostrych ani ukośników odwrotnych. Zduplikowane terminy są usuwane bez rozróżniania wielkości liter.
- Nazwy firm zawierają 1–120 znaków. Instrukcje tłumaczenia na koncie zawierają maksymalnie 500 znaków.
- Zestawy ustawień języków i kanałów dopuszczają maksymalnie 50 zestawów, każdy z 1–50 wybranymi językami lub kanałami. Firmowe zestawy ustawień zamiany tekstu na mowę dopuszczają maksymalnie 10 unikalnych identyfikatorów, nazwy o długości 60 znaków, instrukcje o długości 300 znaków i szybkość od 0.5 do 2.
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_BRAND_VOCABULARY | Co najmniej jeden termin słownictwa nie spełnia zasad dotyczących długości terminu, liczby słów lub znaków. |
| 400 | INVALID_REQUEST_ID | Podaj requestId lub Idempotency-Key w formacie UUID v4. |
| 400 | VALIDATION_ERROR | Obiekt JSON zawiera nieobsługiwane pole, nieprawidłową wartość lub brakuje w nim wymaganego argumentu. |
| 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 | PAID_SUBSCRIPTION_REQUIRED | Zapisywanie nowych lub zmienionych ustawień wstępnych głosu do syntezy mowy wymaga obowiązującej płatnej subskrypcji. |
| 403 | SUBSCRIPTION_REQUIRED | Użyj aktywnej płatnej subskrypcji. |
| 403 | TEAM_OWNER_NOT_FOUND | Nie znaleziono konta faktycznego właściciela zespołu. |
| 403 | TEAM_OWNER_REQUIRED | Ta akcja wymaga konta będącego właścicielem zespołu lub wspólnych ustawień. |
| 404 | ACCOUNT_NOT_FOUND | Nie znaleziono konta lub konta aktywnego obszaru roboczego. |
| 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. |
| 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 | 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": ["settings:write"]
}
}
Czy ta strona była pomocna?