API reference — Text-to-Speech

The contract for invoking a self-hosted Bulbul v3 endpoint. Send model: bulbul:v3 in every request — it is the only accepted value (bulbul:v3-beta and v2 are rejected). Request bodies are JSON; responses are base64 audio (real-time) or a raw audio byte stream (streaming).

Real-time — InvokeEndpoint

Request fields

Response

1
{ "request_id": "20260730_…", "audios": ["<base64 audio>"] }

audios always contains exactly one element (the list is a historical artifact).

Server-side streaming (SSE) — InvokeEndpointWithResponseStream

Call the streaming operation and set "stream": true in the request body. The flag lives in the JSON payload, not in an API parameter — SageMaker relays the body to the container verbatim, so calling the streaming API without the flag returns a single buffered chunk. The response is a sequence of PayloadPart events carrying raw encoded audio; concatenate them. Time-to-first-byte is ~0.5–0.6 s regardless of text length. Max text 3500 characters.

1
resp = runtime.invoke_endpoint_with_response_stream(
2
    EndpointName=endpoint,
3
    ContentType="application/json",
4
    Body=json.dumps({**payload, "output_audio_codec": "mp3", "stream": True}),
5
)
6
for event in resp["Body"]:
7
    part = event.get("PayloadPart")
8
    if part:
9
        audio_out.write(part["Bytes"])

Bidirectional — InvokeEndpointWithBidirectionalStream

A full-duplex session over SigV4 HTTP/2, port 8443 (client aws-sdk-sagemaker-runtime-http2). Put model in the URL-encoded ModelQueryString. Frames are sent with data_type="UTF8":

• Send: {"type":"config","data":{…speaker, language_code, output_audio_codec, speech_sample_rate, pace…}}, then per turn {"type":"text","data":{"text":"…"}} … {"type":"flush"}; {"type":"ping"} keep-alive.
• Receive: {"type":"audio","data":{"audio":"<base64>"}}, {"type":"event","data":{"event_type":"final"}}, and on failure {"type":"error","data":{"message":"…","code":<http status>}}.

Errors

See Error handling on SageMaker for the 424 collapse and the shared envelope. Bad input → 400 invalid_request_error (wrong model, empty or over-length text, unsupported speech_sample_rate, pace out of range, malformed JSON) with a descriptive Pydantic message:

1
{
2
  "error": {
3
    "message": "Validation Error(s):\n- model: Input should be 'bulbul:v3'",
4
    "code": "invalid_request_error",
5
    "request_id": "20260729_…"
6
  }
7
}

Overload → 503 / code: "service_overloaded" with body retry_after (shed immediately, never queued):

1
{
2
  "error": {
3
    "message": "server at capacity, retry later",
4
    "code": "service_overloaded",
5
    "request_id": "20260729_…",
6
    "retry_after": 5
7
  }
8
}