NueForm

语音 API

使用 Voice Studio 的声音，从您自己的代码生成语音：一个声音或整段脚本，任何语言每个朗读字符 0.4 积分，并可先免费估算。

使用 NueSpeak Apex（与 Voice Studio 相同的声音）从您自己的代码生成语音。请求会消耗您 NueForm 余额中的积分：任何语言每个朗读字符 0.4 积分（每 1,000 个字符约 $0.04），每次请求向上取整一次到整数积分。估算免费。

所有请求和响应正文都使用 snake_case 字段名。声音使用 nv_… ID 标识，生成内容使用 gen_… ID 标识。

在您的账户完成首次积分购买（或使用付费计划）并验证邮箱后，Voice 密钥可在所有计划中使用。请参阅语音 API 密钥。

Endpoints
POST/api/v1/voicePOST/api/v1/voicePOST/api/v1/voice/streamGET/api/v1/voice/voicesDELETE/api/v1/voice/voices/:idGET/api/v1/voice/generationsGET/api/v1/voice/generations/:idGET/api/v1/voice/generations/:id/audioDELETE/api/v1/voice/generations/:idGET/api/v1/credits

生成语音

POST/api/v1/voice

生成音频并在完成后应答（同步，每次请求最多 5,000 个朗读字符）。发送 Accept: audio/mpeg（或 audio/wav、audio/ogg、audio/basic、audio/*）即可直接获取音频；否则返回 JSON，其中包含需要认证的 audio.url。

积分在请求开始时扣除。失败的台词会自动退还积分，以错误结束的请求不收取任何费用。已扣费的请求绝不会以错误结束：如果音频未能及时生成，会返回 202 并附带 Location 响应头。请从那里获取音频，不要重新发送请求。

请求正文

modestring

"speak"（一个声音朗读 text）、"script"（多个声音）或 "estimate"（参见估算费用）

textstring

speak：要朗读的文字

voicestring

来自列出声音的 nv_… 声音。speak 必填；在 script 中，用于没有角色标签的台词

linesarray

script：结构化台词，每项为 {"speaker", "voice", "text"} 或停顿 {"pause_ms": 800}（最多 10,000）

scriptstring

script：多声音格式，每个角色一行：[Maya] Did you hear that?

castarray

script：为每个带标签的角色指定一个声音，[{"speaker": "Maya", "voice": "nv_…"}]

auto_convertboolean

先将粘贴的剧本或聊天记录（MAYA: Hi）转换为多声音格式。免费，有每日限额

auto_castboolean

为每个没有声音的角色挑选声音。免费，有每日限额。脚本不是英语时请发送 language

languagestring

语言名称或代码（"es"、"Spanish"）。默认：声音本身的语言

qualitystring

"standard"（默认）、"studio" 或 "phone"。价格相同

speednumber

0.85 到 1.15（默认 1）

formatstring

"mp3"（默认）、"wav"、"ogg_opus" 或 "mulaw_8k"

max_creditsinteger

如果费用更高，则拒绝请求（409，不收费）

reuseboolean

默认 true：过去 30 天内完全相同的请求会以 0 积分返回该音频

saveboolean

true 会保留音频，直到您删除它。默认：30 天后删除

retake_ofstring

重新生成某个生成内容（参见重录）

titlestring

在您的 Library 中显示的标题

响应字段

idstring

生成内容（gen_…）

statusstring

"ready"、"rendering"（202：仍在生成）、"partial"（部分台词失败且不收费）或 "failed"

audioobject or null

url（请携带您的 API 密钥）、format、sample_rate、duration_seconds、retained_until

creditsobject

estimated、charged（本次请求收取的积分）和 remaining

linesarray

仅 script：每行台词的 speaker、voice、text、status、start_ms、end_ms 和 credits

retakes_remaininginteger

此片段剩余的免费重录次数

reusedboolean

以 0 积分返回的、此前相同请求的音频

代码示例

bash
curl -X POST https://nueform.io/api/v1/voice \
  -H "Authorization: Bearer $NUEFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: audio/mpeg" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "mode": "speak",
    "voice": "nv_7QmS2xK9aLpe3vT8a",
    "text": "Fresh bread every morning at seven. Croissants too. See you on Main Street."
  }' \
  --output speech.mp3 --dump-header -

这段文字有 75 个朗读字符，因此费用为 30 积分（75 × 0.4）。

响应头

text
HTTP/1.1 200 OK
Content-Type: audio/mpeg
NueForm-Generation-Id: gen_2cH4kXyQ9vLmNp3Rs
NueForm-Credits-Estimated: 30
NueForm-Credits-Charged: 30
NueForm-Credits-Remaining: 48730
NueForm-Rate-Card: 1
NueForm-Retakes-Remaining: 2
NueForm-Audio-Duration: 4.8
Idempotent-Replayed: false
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 2026-11-04T18:13:00.000Z

JSON 响应

json
{
  "data": {
    "id": "gen_2cH4kXyQ9vLmNp3Rs",
    "object": "voice.generation",
    "status": "ready",
    "mode": "speak",
    "source": "api",
    "voice": { "id": "nv_7QmS2xK9aLpe3vT8a", "name": "Amara" },
    "language": "English",
    "characters": 75,
    "audio": {
      "url": "https://nueform.io/api/v1/voice/generations/gen_2cH4kXyQ9vLmNp3Rs/audio?format=mp3",
      "format": "mp3",
      "sample_rate": 24000,
      "duration_seconds": 4.8,
      "retained_until": "2026-12-04T18:12:00.000Z"
    },
    "credits": { "estimated": 30, "charged": 30, "remaining": 48730 },
    "retakes_remaining": 2,
    "reused": false,
    "created_at": "2026-11-04T18:12:00.000Z"
  },
  "meta": { "rate_card": "1" }
}

脚本

脚本会在一个音频文件中用多个声音朗读。发送结构化的 lines（完全不做解析），或发送多声音格式的 script 及其 cast。停顿（{"pause_ms": 800}，或脚本中的 (pause 2s)）不收费；只对朗读字符计费。

响应会附加 lines：每行台词在音频中的开始和结束位置、状态，以及其字符折合的积分（credits，小数）。请求只收费一次，向上取整。失败的台词显示 "credits": 0，不收取费用。

使用 auto_convert 时，会先转换粘贴的剧本或聊天记录；使用 auto_cast 时，每个没有声音的角色都会分配到一个声音。

请求示例

json
{
  "mode": "script",
  "lines": [
    { "speaker": "Maya", "voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Did you hear that?" },
    { "speaker": "Leo", "voice": "nv_P3vT8aLeQ2mwX4kZ9", "text": "Hear what?" },
    { "pause_ms": 800 },
    { "speaker": "Maya", "voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Exactly. Nothing." }
  ],
  "format": "wav"
}

或使用多声音格式

json
{
  "mode": "script",
  "script": "[Maya] Did you hear that?\n[Leo] Hear what?\n(pause 1s)\n[Maya] Exactly. Nothing.",
  "auto_cast": true
}

估算费用

POST/api/v1/voice

"mode": "estimate" 接受与 speak 或 script 相同的正文，返回确切费用，不生成任何内容。估算免费，且不计入您的生成限额（每个密钥每分钟最多 300 次）。

响应字段

charactersinteger

朗读字符：计费依据

creditsinteger

该请求将收取的确切积分

seconds_estimatednumber

音频的大致时长

balanceinteger

您当前的余额

enoughboolean

您的余额（以及密钥的月度限额，如有）足以支付

示例

bash
curl -X POST https://nueform.io/api/v1/voice \
  -H "Authorization: Bearer $NUEFORM_API_KEY" \
  -d '{"mode": "estimate", "voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Fresh bread every morning at seven. Croissants too. See you on Main Street."}'
json
{
  "data": {
    "object": "voice.estimate",
    "characters": 75,
    "credits": 30,
    "seconds_estimated": 4.8,
    "balance": 48760,
    "enough": true
  },
  "meta": { "rate_card": "1" }
}

流式语音

POST/api/v1/voice/stream

在音频生成的同时将其发送，让您的应用约一秒即可开始播放，而无需等待整段片段：适用于智能体、语音机器人和朗读器。由一个声音朗读 text。语音引擎已预热时，无论文本多长，首段音频通常在 1–2 秒内到达。

价格与生成语音相同：每个朗读字符 0.4 积分，每次请求向上取整一次，在流开始时扣除。每个流最多约 200 秒语音：英语约 3,100 个字符，语速较慢的语言更少（更长的文本返回 413 TEXT_TOO_LONG 并附带 max_characters）。更长的文本请发送多个流，或使用 POST /api/v1/voice。

在第一个字节之前，任何失败都是普通错误，不收取任何费用：如果语音引擎在产生任何音频之前失败，扣费会退还（500，或在引擎启动期间返回带 Retry-After 的 503 WARMING_UP）。第一个字节之后状态无法再更改，因此中途失败的流会在结束之前停止：您的 HTTP 客户端会报告响应体不完整。请使用 NueForm-Generation-Id 配合获取生成内容查看已保存的副本及其费用。如果您中途断开，流仍会完成并保存，且不会退还积分。

每个流也会保存为一次生成：它会出现在您的 Library 中，下载音频提供它的音频，与每段片段一样经过响度标准化。

流式还是 /voice？ 当有人正在等待收听时使用流式（智能体、语音机器人、朗读）。文件、多声音脚本、speed、重录和估算请使用 POST /api/v1/voice。MCP 工具不支持流式：它们以 /voice 的方式生成音频。

请求正文

voicestring

来自列出声音的 nv_… 声音

textstring

要朗读的文字

formatstring

"mp3"（默认，适用于浏览器）、"pcm_24k"（24,000 Hz 原始 16 位小端单声道 PCM，适用于智能体）或 "mulaw_8k"（8 kHz G.711 μ-law，适用于电话；也可写作 "ulaw_8000"）

languagestring

语言名称或代码。默认：该声音自身的语言

qualitystring

"standard"（默认；mulaw_8k 时为 "phone"）、"studio" 或 "phone"。价格相同

max_creditsinteger

如果费用更高，则拒绝请求（409，不收费）

saveboolean

true 会保留已保存的副本，直到您删除它。默认：30 天后删除

titlestring

在您的 Library 中显示的标题

流式不支持 speed、脚本、retake_of 和 reuse（400，reason: "not_on_stream"）。

代码示例

bash
curl -N -X POST https://nueform.io/api/v1/voice/stream \
  -H "Authorization: Bearer $NUEFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice": "nv_7QmS2xK9aLpe3vT8a", "text": "Fresh bread every morning at seven.", "format": "mp3"}' \
  --output stream.mp3

这段文字有 35 个朗读字符，因此费用为 14 积分（35 × 0.4）。

响应头

text
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
NueForm-Generation-Id: gen_2cH4kXyQ9vLmNp3Rs
NueForm-Credits-Estimated: 14
NueForm-Credits-Charged: 14
NueForm-Credits-Remaining: 48716
NueForm-Rate-Card: 1
NueForm-Audio-Format: pcm_24k
NueForm-Audio-Encoding: pcm_s16le
NueForm-Audio-Sample-Rate: 24000
NueForm-Audio-Channels: 1
X-Accel-Buffering: no

重录

发送 {"mode": "speak", "retake_of": "gen_…"}，即可用相同的文字、声音、语言、质量和语速重新生成。与 retake_of 一起只能发送 mode、format、max_credits 和 save。

  • 免费：生成后 24 小时内可免费重录两次，前提是该密钥本月的免费重录字符不超过其本月计费字符的四分之一。免费重录保持相同的 gen_… ID。
  • 否则：会作为新的生成内容，像任何请求一样收费（每个字符 0.4 积分），retake_of 会指明被重录的那个生成内容。

将 "mode": "estimate" 与 retake_of 一起发送即可提前查看：响应会显示 "free": true 或所需费用。

幂等性

为 speak 和 script 请求发送 Idempotency-Key 请求头（1–255 个字符，例如 UUID），重试就永远不会重复收费：

  • 相同的密钥加相同的正文，会再次返回第一次请求生成的内容，不收费（Idempotent-Replayed: true，NueForm-Credits-Charged: 0）；
  • 相同的密钥加不同的正文，返回 409 CONFLICT，reason: "idempotency_conflict"；
  • 第一次请求仍在进行时，返回 409 CONFLICT，reason: "request_in_progress"，并附带 Retry-After。

每个 API 密钥的 Idempotency-Key 会保留 24 小时。

对于流式请求，相同的密钥加相同的请求体会以 JSON 应答：即第一次请求生成的内容（不会再次流式传输）。

响应头

每个响应都会说明费用：

响应头含义
NueForm-Generation-Id生成内容（gen_…）
NueForm-Credits-Estimated该请求的报价
NueForm-Credits-Charged本次请求收取的积分，已扣除任何自动退还（估算、复用的片段、免费重录、重放和任何错误均为 0）
NueForm-Credits-Remaining之后的余额
NueForm-Rate-Card计费所依据的价目表版本
NueForm-Retakes-Remaining此片段剩余的免费重录次数
NueForm-Audio-Duration音频时长（秒）
Idempotent-Replayed使用 Idempotency-Key 时：此响应是否对应之前的请求
NueForm-Audio-Format, NueForm-Audio-Encoding, NueForm-Audio-Sample-Rate, NueForm-Audio-Channels流的音频：格式、编码、采样率和声道数
X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset此密钥在本分钟内的请求（参见速率限制）

列出声音

GET/api/v1/voice/voices

先列出 NueForm 的预置声音，再列出您自己和您团队的声音，每个声音都带有 nv_… ID、语言、免费试听和语速。免费。

查询参数

sourcestring

"all"（默认）、"stock" 或 "mine"

languagestring

语言名称或代码

genderstring

例如 "female"

qstring

搜索名称、风格和标签

featuredboolean

true：仅精选的预置声音

响应

json
{
  "data": [
    {
      "id": "nv_7QmS2xK9aLpe3vT8a",
      "object": "voice",
      "name": "Amara",
      "source": "stock",
      "type": "clone",
      "language": "English",
      "language_label": "English (US)",
      "gender": "female",
      "age": null,
      "style": "Warm",
      "featured": true,
      "preview_url": "https://nueform.io/voice-previews/amara.mp3",
      "team_id": null,
      "can_delete": false,
      "chars_per_second": 15.5,
      "created_at": null
    }
  ],
  "meta": { "count": 1 }
}

删除声音

DELETE/api/v1/voice/voices/:id

永久删除您的一个声音：先删除其样本、提示和试听，再删除声音本身。积分不予退还。只要仍有表单或电话号码在使用该声音，就会返回 409 CONFLICT，reason: "voice_in_use" 以及使用数量；发送 ?replacement=nv_… 可先将它们切换到另一个声音。

响应

json
{
  "data": {
    "id": "nv_9LmQ2xT4aPe7vK3sW",
    "object": "voice",
    "deleted": true,
    "switched": { "forms": 2, "numbers": 1 },
    "forms_to_republish": 1
  }
}

列出生成内容

GET/api/v1/voice/generations

您的生成内容，按从新到旧排列。使用 meta.next_cursor 翻页。

查询参数

limitinteger

1 到 100（默认 20）

cursorstring

上一页的 next_cursor

sourcestring

仅限通过 "api"、"studio"、"mcp" 或 "app" 生成的内容

响应

json
{
  "data": [
    { "id": "gen_2cH4kXyQ9vLmNp3Rs", "object": "voice.generation", "status": "ready", "credits": { "charged": 30 } }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}

获取生成内容

GET/api/v1/voice/generations/:id

单个生成内容；若为脚本，则包含其 lines。此处的 credits.charged 是它的总费用，已扣除任何自动退还。

下载音频

GET/api/v1/voice/generations/:id/audio

使用您的 API 密钥流式获取音频本身（支持字节范围）。?format= 可为 mp3（默认）、wav、ogg_opus 或 mulaw_8k。Ogg/Opus 和 8 kHz μ-law 在首次请求时生成：返回 202 表示"请在 Retry-After 秒后重试"。免费。

删除生成内容

DELETE/api/v1/voice/generations/:id

永久删除生成内容及其音频。积分不予退还。仍在生成中的内容会返回 409 CONFLICT，reason: "still_rendering"。

查询积分

GET/api/v1/credits

您的密钥消费所用的余额、该密钥本月的使用情况以及价目表。只读，可使用 Voice 密钥或完全访问密钥。

响应字段

balanceinteger

您现在可以花费的积分（10,000 积分 = $1）

approxstring

以美元表示的余额

keyobject

此密钥的 monthly_credit_limit（null 表示无限额）、spent_this_month、paused 和 resets_at（每月 1 日，UTC）

voice_apiobject

credits_per_character（0.4）、取整方式，以及估算免费

rate_cardobject

按操作列出的所有价格

响应

json
{
  "data": {
    "object": "credits",
    "balance": 48730,
    "approx": "≈ $4.87",
    "currency": "usd",
    "frozen": false,
    "key": {
      "id_prefix": "nf_a1b2c3d4",
      "monthly_credit_limit": 100000,
      "spent_this_month": 1240,
      "paused": false,
      "resets_at": "2026-12-01T00:00:00.000Z"
    },
    "voice_api": { "credits_per_character": 0.4, "rounding": "up_per_request", "estimate_free": true }
  },
  "meta": { "rate_card": "1" }
}

价格

项目积分美元
通过语音 API 生成语音每个朗读字符 0.4，任何语言每 1,000 个字符约 $0.04
估算0免费
复用的片段（reuse）0免费
重录24 小时内两次 0（合理使用），之后每个字符 0.4

积分来自积分包（$5 起，可得 50,000 积分），永不过期。密钥可以设置月度积分上限：花费达到上限后，在下月 1 日之前其生成语音和删除请求会收到 403 FORBIDDEN，reason: "key_limit_reached"（仍可列出和下载已生成的内容），您的其他密钥不受影响。请求使用密钥所有者在钱包的 Voice Studio 付款来源 中选择的积分支付：默认为其本人的积分，除非选择了某个团队。团队无法支付时，绝不会改用其本人的积分：请求会收到 403 FORBIDDEN，reason: "team_payer_unavailable"；达到成员月度上限时为 reason: "member_cap_reached"，且不会扣费。

错误

所有错误都使用标准错误格式，以错误结束的请求不收取任何费用。最常见的错误：

状态code何时出现
402INSUFFICIENT_CREDITS您的余额不足以支付请求（credits_required、credits_available、top_up_url；若是密钥所有者选择的付款团队积分不足，则为 payer: "team"，此时 top_up_url 打开钱包，可在 Voice Studio 付款来源 中改为使用本人的积分）
403FORBIDDENreason：key_limit_reached、account_gate、scope_not_allowed、cooldown、voice_studio_suspended、wallet_frozen、member_cap_reached、team_payer_unavailable
409CONFLICTreason：quote_exceeds_max_credits、idempotency_conflict、request_in_progress、unit_rendering
413TEXT_TOO_LONG超过 5,000 个朗读字符（max_characters）
422CONTENT_BLOCKED、VOICE_UNAVAILABLE、LANGUAGE_NOT_SUPPORTED_BY_VOICE、INVALID_SCRIPT文字或声音无法按所发送的内容朗读
429RATE_LIMITED、CONCURRENCY_LIMIT请求过多（参见速率限制）
503CAPACITY、WARMING_UP、MODERATION_UNAVAILABLE、AI_UNAVAILABLE请在 Retry-After 秒后重试
最后更新：2026年10月20日