Create Share Link Session | SpeechifyAI API

Start a realtime voice session against a share link.

Unauthenticated: the link token is the credential, and it is sent in the request body rather than the URL so it never reaches request logs. The agent’s owner is billed for the call.

The response carries only the realtime handles — token and url — which is exactly the shape the <speechify-agent> element’s sessionProvider expects. It deliberately omits the conversation id and the agent snapshot that createSession returns, because those are owner-side facts an anonymous visitor should not hold.

Call time is claimed from the link’s budget before anything is dispatched. A link with too little budget left for another call answers 409 share_link_exhausted; one already running its maximum number of simultaneous calls answers 429.

Start a realtime voice session against a share link. Unauthenticated: the link token is the credential, and it is sent in the request body rather than the URL so it never reaches request logs. The agent's owner is billed for the call. The response carries only the realtime handles — `token` and `url` — which is exactly the shape the `<speechify-agent>` element's `sessionProvider` expects. It deliberately omits the conversation id and the agent snapshot that `createSession` returns, because those are owner-side facts an anonymous visitor should not hold. Call time is claimed from the link's budget before anything is dispatched. A link with too little budget left for another call answers `409 share_link_exhausted`; one already running its maximum number of simultaneous calls answers `429`.

Request

This endpoint expects an object.

tokenstringRequired

The share link's opaque bearer token.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The realtime handles for the new session.

tokenstring

The realtime access token for the session.

urlstring

The realtime server URL to connect to.

Errors

400

Bad Request Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error