Create a session

Creates a session and returns its token. The token is returned here and in GET /v2/sessions/{id}. List responses do not include it.

Repeating the call with the same client_reference_id creates an independent session. Each session has its own id, token and lifetime.

Request Body — REQUIRED
intent string — REQUIRED Possible values: [s2s, stt, tts] Product the session token is valid for: s2s: speech-to-speech translation stt: speech-to-text tts: text-to-speech A token presented to a different product is refused.
connection_type string Possible values: [ws, webrtc] Transport the end user will connect with. webrtc is available for s2s only. A token issued for one transport cannot be used with the other.
expires_in_seconds integer Possible values: 60 ≤ value ≤ 86400 Connect window: how long after creation the token can open a new stream. Streams already running are not affected when the window closes. To extend, issue a new session.
max_session_duration_seconds integer Possible values: 60 ≤ value ≤ 18000 Maximum duration of any single stream opened with this token, counted from that stream's own start. The stream is closed when it is reached. When omitted, streams are limited only by your account limits.
single_use boolean true: the token opens exactly one stream in its lifetime. A second connection while that stream is running is refused, usually with HTTP 409 session_in_use. After the stream ends, every connection is refused with HTTP 409 session_already_used. In both cases the application must request a new session; connecting again with the same token does not help. false: the token can open several streams, one after another, until the connect window closes. One connection is live at a time. Over ws a second connection while the first one is live is refused with HTTP 409 session_in_use; connect again after the first one ends. Over webrtc a new connection replaces the previous one. The live stream counts toward your concurrent session limit.
client_reference_id string Possible values: length ≤ 256 Your own identifier for the customer, device or order this session belongs to. Stored as is, not unique, and used to filter sessions and usage. Set it from your server; end users cannot change it.
subscriber_count integer Possible values: value ≤ 100 Number of listener tokens to issue alongside the publisher token. Available for s2s over webrtc only. Listener tokens can join the room and receive the translation but cannot publish audio or change the translation task. Listeners do not count toward your concurrent session limit.

Responses
201 Session created. Schema — OPTIONAL ok boolean Possible values: [true] data object id string Session identifier. Use it to inspect, revoke and report on the session. token string — OPTIONAL Credential the end user connects with. Returned by POST /v2/sessions and GET /v2/sessions/{id} only. intent string Possible values: [s2s, stt, tts] Product the session token is valid for: s2s: speech-to-speech translation stt: speech-to-text tts: text-to-speech A token presented to a different product is refused. connection_type string Possible values: [ws, webrtc] Transport the end user will connect with. webrtc is available for s2s only. A token issued for one transport cannot be used with the other. single_use boolean true if the token opens only one stream in its lifetime. client_reference_id string — OPTIONAL Possible values: length ≤ 256 Your identifier from the create request. status string Possible values: [pending, active, idle, used, expired, revoked] pending: issued, no stream opened yet, connect window still open active: at least one stream is running idle: reusable token that has been used before, no stream running, connect window still open used: single-use token whose stream has finished; cannot be used again expired: connect window has passed and no stream is running revoked: revoked by you created_at date-time When the session was created. connect_by date-time Moment after which the token can no longer open a new stream. max_session_duration_seconds integer — OPTIONAL Duration cap applied to each stream, if one was set. first_connected_at date-time — OPTIONAL When the first stream was opened with this token, or null if none yet. active_stream_count integer Number of streams running with this token. webrtc object — OPTIONAL Present for connection_type: webrtc only. url string WebRTC endpoint the publisher and listeners connect to. room_name string Room the session runs in. subscriber_keys string[] — OPTIONAL Listener tokens, one per requested subscriber. Returned on creation only.
401
402
403
422
424
429
500