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"
}
设置和通知
更新账户设置
更新支持的个人设置。只有团队所有者才能更改共享词汇和翻译指令。省略的设置保持不变。
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"
}
更新支持的个人设置。只有团队所有者才能更改共享词汇和翻译指令。省略的设置保持不变。
所需权限:
POST https://api.voicecheap.ai/v1/actions/settings_update
身份验证和权限
string
必填
在此请求头中发送 VoiceCheap API 密钥。也支持通过 Authorization: Bearer 发送同一 API 密钥。OAuth 访问令牌仅适用于 MCP，此 REST 端点不接受 OAuth
访问令牌。
settings: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
文本值。最小长度: 1. 最大长度: 120.
array
值列表。项目结构请参阅完整输入架构。最多项目数: 1000.
string
文本值。最大长度: 500.
union
接受完整输入架构中列出的备选项。
array
值列表。项目结构请参阅完整输入架构。最多项目数: 50.
array
值列表。项目结构请参阅完整输入架构。最多项目数: 50.
array
值列表。项目结构请参阅完整输入架构。最多项目数: 10.
object
JSON 对象。嵌套字段请参阅完整输入架构。
boolean
布尔值。
boolean
布尔值。
完整输入架构
完整输入架构
以下 JSON Schema 保留了发现接口公开的确切字段名、嵌套类型、默认值、范围和可接受值。其他跨字段规则列于操作说明中。
{
"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
}
幂等性
为每次修改操作在 requestId 或 Idempotency-Key HTTP 请求头中提供 UUID v4。网络故障后，请使用相同标识符和完全相同的参数重试。如果同时提供这两个值，它们必须一致。重放已保存的请求不会重复执行操作，也不会再次扣除月度调用次数。失败或中断的请求不会自动重新执行。 对于每次修改操作，如果重试时发现同一请求仍在运行，即使首次执行通常为同步操作，也可能返回 HTTP 202。如果执行已完成但 resultStored 为 false，重试会返回 HTTP 200 和已保存的请求状态，而非原始结果。请通过对应领域的历史记录、结果或下载操作获取输出。请求示例
请将示例资源标识符和媒体键替换为账户返回的值。重试同一次修改操作时，请保持请求标识符不变。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)
响应
首次执行成功时返回 HTTP 200，操作结果位于 data 下。重放请求时可能改为返回已保存的请求状态。示例展示了一种支持的响应，并未包含所有可选字段。 确认所提供的受支持设置已保存。{
"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"
}
结果字段
| 字段 | 说明 |
|---|---|
data.updated | 设置更新完成后为 true。 |
恢复并轮询此请求
即使连接丢失，也应使用同一标识符。如果 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":"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
}
}
}
操作说明
- 除可选的 requestId 外，至少提供一项设置。省略的设置保持不变。
- 只有团队所有者可以更改 brandVocabulary 和 customTranslationInstructions。团队成员可以更新自己的其他偏好设置。
- 词汇表最多接受 1,000 个术语。每个规范化后的术语最多包含 49 个字符和五个单词，且不得包含方括号、花括号、尖括号或反斜杠。重复术语会按不区分大小写的方式去重。
- 公司名称须包含 1–120 个字符。账户翻译说明最多包含 500 个字符。
- 语言和频道预设最多允许 50 个预设，每个预设选择 1–50 项语言或频道。文本转语音品牌预设最多允许 10 个唯一 ID、最长 60 个字符的名称、最长 300 个字符的说明，以及 0.5 到 2 的 speed。
用量
每次成功调用消耗一次月度 API/MCP 调用额度。媒体额度和操作本身的生成限额也适用。错误
| HTTP 状态 | 代码 | 含义或恢复方式 |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | 凭证通过 access_token 或 api_key 查询参数提供。请在标头中发送凭证。 |
| 400 | IDEMPOTENCY_CONFLICT | Idempotency-Key 请求头必须与请求体中的 requestId 字段一致。 |
| 400 | INVALID_BRAND_VOCABULARY | 一个或多个词汇项不符合术语长度、词数或字符规则。 |
| 400 | INVALID_REQUEST_ID | 请在 requestId 或 Idempotency-Key 中提供 UUID v4。 |
| 400 | VALIDATION_ERROR | JSON 对象包含不受支持的字段、无效值，或缺少必需参数。 |
| 401 | API_KEY_EXPIRED | API 密钥已过期。 |
| 401 | INVALID_API_KEY | 请提供有效且未过期的 API 密钥。 |
| 401 | INVALID_CREDENTIAL | Authorization 标头格式错误或与 x-api-key 冲突。 |
| 401 | MISSING_CREDENTIAL | 未提供可用的请求头凭据，或其长度超过 4096 个字符。 |
| 401 | USER_NOT_FOUND | 该凭据对应的账户已不存在。 |
| 403 | ACCOUNT_UNAVAILABLE | 调用者账户或计费账户不可用，或正在删除。 |
| 403 | AMBIGUOUS_TEAM_API_KEY | 此凭据对应的用户属于多个团队，因此计费上下文不明确。 |
| 403 | INSUFFICIENT_SCOPE | 请授予全部所需权限，或选择其他凭据。 |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | 无法验证该账户的集成限制。 |
| 403 | PAID_SUBSCRIPTION_REQUIRED | 保存新增或修改后的文本转语音音色预设需要有效的付费订阅。 |
| 403 | SUBSCRIPTION_REQUIRED | 请使用有效的付费订阅。 |
| 403 | TEAM_OWNER_NOT_FOUND | 找不到实际生效的团队所有者账户。 |
| 403 | TEAM_OWNER_REQUIRED | 此操作要求使用拥有团队或共用设置的账户。 |
| 404 | ACCOUNT_NOT_FOUND | 找不到账户或当前工作区账户。 |
| 409 | CONCURRENT_ACTION_LIMIT_REACHED | 此账户已有 10 个集成操作正在运行。请先轮询现有请求，再启动另一个操作。 |
| 409 | IDEMPOTENCY_CONFLICT | 只有操作和参数完全相同时，才能复用标识符。 |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | 请等待月度额度重置，或更改套餐。 |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | 如果提供了 Retry-After，请等待其指定的时间，并采用退避重试。 |
| 500 | INTERNAL_ERROR | 在决定是否重试修改操作前，请检查已保存的请求状态和资源历史记录。 |
| 503 | ACTION_RESULT_UNAVAILABLE | 操作已执行，但未能保存结果。在启动新的生成前，请检查已保存的请求状态和资源历史记录。 |
| 503 | SERVER_RESTARTING | 服务器正在重启。请稍后重试；对于修改操作，请保持请求标识符不变。 |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["settings:write"]
}
}
此页面对您有帮助吗？