Atmee.aiDocs
APIAPI referenceSpeech sessions

Read a speech session's state, end reason and cost

GET
/v1/speech_sessions/{session_id}

status is active while the session is reserved or connected, then completed or failed. connectedAt is when billing started (the speech server's first usage report), endsAt when the session's time runs out, endRequestedAt when you ended it while a connection was open (until its next usage report settles it). Once it ended, endReason says why and billedSeconds / chargedMicrocredits what it cost (100 microcredits = 1 credit).

Authorization

headerX-Api-Key<token>

Secret embed API key (sk_atmee_...; keys minted before 2026-09 carry sk_live_...), held by the customer's own backend and never sent to a browser. Format: X-Api-Key: sk_atmee_....

Path Parameters

session_id*string

The speech session's id, as POST /v1/speech_sessions returned it.

Formatuuid

Response Body

The session's durable state.

application/json
  1. response
sessionId*string
Formatuuid
status*string
Value in"pending""active""completed""failed"
avatarId?string
Formatuuid
language?string
actualDurationSeconds*integer

The length granted.

createdAt?string
Formatdate-time
connectedAt?string

When billing started (the speech server's first usage report); null until then.

Formatdate-time
endsAt*string

When the session's time runs out (the reservation plus actualDurationSeconds).

Formatdate-time
endRequestedAt?string

When you ended the session while a connection was open; it settles at the connection's next usage report (within 30 s).

Formatdate-time
endedAt?string
Formatdate-time
endReason?string

Why it ended (user_left, max_duration, balance_exhausted, ended_by_api, error, ...; see AvatarSessionStatusResponse.endReason); null while it is live.

failureCode?string
billingMode*string
Value in"reserve""metered"
billedSeconds?integer
chargedMicrocredits?integer
Example Request
curl -X GET 'https://api.atmanity.us/v1/speech_sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",  "status": "pending",  "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67",  "language": "string",  "actualDurationSeconds": 0,  "createdAt": "2019-08-24T14:15:22Z",  "connectedAt": "2019-08-24T14:15:22Z",  "endsAt": "2019-08-24T14:15:22Z",  "endRequestedAt": "2019-08-24T14:15:22Z",  "endedAt": "2019-08-24T14:15:22Z",  "endReason": "string",  "failureCode": "string",  "billingMode": "reserve",  "billedSeconds": 0,  "chargedMicrocredits": 0}

Start a speech-to-speech session (audio only, no video) POST

Reserves a speech session with an avatar: a realtime speech-to-speech conversation over a WebSocket, without video.

End a speech session POST

Ends the session (completed, endReason: ended_by_api).

Read a speech session's state, end reason and cost — Atmee Docs