Generate speech
POST
https://api.vidmoat.com/v1/ai/speechBearer tokenScope
ai.speech8 credits Grok; 15 credits OpenAI; 45 credits CartesiaTry it in the playgroundAI-generated speech, up to 1,000 characters (longer text is cut and the response says where). provider:auto/grok/openai/cartesia; optional voiceId, language, speed, OpenAI instructions for delivery, and a Cartesia emotion. quoteOnly:true quotes without spending. Auto may fall back after a confirmed quota rejection within maxCredits; a named voice stays pinned. Creator and Studio.
Body#
textstringrequiredWhat to say. Over 1,000 characters is cut, andtruncatedreports it.providerenumdefaultautoWho generates it. Auto picks the cheapest that can; Cartesia is chosen by name, by an emotion, or as the last fallback.One ofauto,grok,openai,cartesiavoiceIdstringOpenAI: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse, marin (default), cedar. Grok: eve (default), ara, leo, rex, sal. Cartesia: lauren (default), sebastian, quentin, jolene, gemma, archie, tanner, ronald, katie, arlo, nandi, zanele, or a Cartesia voice id. A voice only one provider has pins that provider.languagestringautoor a language code.speednumberdefault10.7 to 1.5.instructionsstringOpenAI only, up to 500 characters: how to deliver the line.emotionstringCartesia only: a named emotion such as calm, excited or sad. Setting it routes to Cartesia.maxCreditsnumberNever spend more than this. Routes above it are excluded.quoteOnlybooleantruereturns the route and price without generating or charging.
Response#
Returns 200.
Response fields#
urlstringThe audio file. Use as a clipsrc.routeobjectThe provider route chosen:provider,model,credits,maxCredits,reasonandpolicy(andvoiceIdfor speech).aiGeneratedbooleanAlwaystrue.creditsobject{ charged, remaining }: what this call cost and the balance after it.truncatedobjectPresent when the text was cut:{ at, droppedChars, note }.hintstringWhat to do with it.quoteOnlybooleanWithquoteOnly: truethe reply is only{ route, quoteOnly: true }.
Errors#
Besides the errors any request can get (authentication, rate limits):
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | No text; a speed, language or voiceId that is not offered; instructions with a provider other than OpenAI, or emotion with one other than Cartesia; maxCredits below every route's price; or the chosen provider is not configured. |
| 402 | plan_required | The plan has no speech generation. |
| 402 | insufficient_credits | The balance cannot cover the call. Nothing ran. remaining is the balance. |
| 422 | prompt_rejected | The prompt failed the safety check. Nothing was charged. field names the field. |
| 502 | provider_error | The generation provider failed. The charge is refunded. |