# Live calls

`GET | POST /v1/live/sessions` — A live video call with one of your characters: their face, their voice, in real time.

- Base URL: https://eroq.ai/v1
- Auth: `Authorization: Bearer eroq_sk_…` (create keys at https://eroq.ai/dashboard/keys)
- Credits: 100 credits per minute, bought ahead (the first minute when the call opens)

A **live call** puts the caller face to face with a character: the character hears them, answers in their own voice and their portrait talks, lip-synced, at 25 frames per second (512×512). The media runs over WebRTC between the caller's browser and eroq's call worker; eroq only relays the signalling. The character needs a portrait (`avatarUrl`); their persona and voice (`voiceId`, else their gender's roster voice) are the ones the chat and /v1/audio/speech use.

**The flow.** `POST /v1/live/sessions` with `character` buys the first minute and returns `ice_servers`. Create an `RTCPeerConnection` with them, add the microphone track (`sendrecv`) then a video transceiver (`sendrecv`, no track: the face comes back on it), gather ICE, and send the local description to `POST /v1/live/sessions/{id}/offer`. Poll `GET /v1/live/sessions/{id}` (about once a second) until `answer` is set and pass it to `setRemoteDescription` — a warm worker answers in a second or two, a cold one boots first (up to ~40 s). A call nobody picks up within 150 s fails and gives its minute back.

**Billing, minute by minute.** Time is bought ahead: the call goes on while the connected seconds stay within `paid_seconds`, and the worker ends it a few seconds after. Buy the next minute with `POST /v1/live/sessions/{id}/extend` before the current one runs out (the studio does it 20 s ahead); `402 insufficient_credits` there means the call ends when the bought time is over. `POST /v1/live/sessions/{id}/end` hangs up; a call that never connected gives its first minute back.

The caller's words meet the same content policy as the chat (fiction between adults, nothing involving minors): a refused line is answered by the character changing the subject. A workspace holds two open calls at a time; a call lasts two hours at most.

## Operations

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | `/v1/live/sessions` | Open a call with a character: buys the first minute, returns the ICE servers. |
| `POST` | `/v1/live/sessions/{id}/offer` | Send the browser's WebRTC offer: the call starts ringing. |
| `GET` | `/v1/live/sessions/{id}` | The call as it stands — the worker's `answer` once it picks up. |
| `POST` | `/v1/live/sessions/{id}/extend` | Buy more time before the bought minutes run out. |
| `POST` | `/v1/live/sessions/{id}/end` | Hang up. A call that never connected gives its minute back. |

## POST /v1/live/sessions

Open a call with a character: buys the first minute, returns the ICE servers.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `character` | string | yes | One of your characters (GET /v1/characters) — it needs a portrait. |
| `user` | string | no | Your end user (an opaque id), kept on the call and the ledger. |

### Example request

```bash
curl https://eroq.ai/v1/live/sessions \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "character": "9c1e2d4a-6b7f-4c3d-9e8a-1f2b3c4d5e6f"
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/live/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "character": "9c1e2d4a-6b7f-4c3d-9e8a-1f2b3c4d5e6f"
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/live/sessions",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "character": "9c1e2d4a-6b7f-4c3d-9e8a-1f2b3c4d5e6f"
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "character": "9c1e2d4a-6b7f-4c3d-9e8a-1f2b3c4d5e6f"
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/live/sessions", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
"id": "live_3f9a1c2b7d8e4f60", "object": "live.session", "status": "created",
"character": "9c1e…", "answer": null,
"ice_servers": [{ "urls": ["stun:stun.cloudflare.com:3478", "turn:turn.cloudflare.com:3478?transport=udp"], "username": "…", "credential": "…" }],
"credits_per_minute": 100, "paid_seconds": 60, "seconds": 0, "credits_spent": 100,
"credits_remaining": 1700
}
```

## POST /v1/live/sessions/{id}/offer

Send the browser's WebRTC offer: the call starts ringing.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sdp` | string | yes | The RTCPeerConnection local description, ICE gathered. |
| `type` | string | no | `offer`. |

### Example request

```bash
curl https://eroq.ai/v1/live/sessions/SESSION_ID/offer \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "offer",
  "sdp": "v=0\r\no=- 4611731400430051336 2 IN IP4 127.0.0.1\r\n…"
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/live/sessions/SESSION_ID/offer', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "offer",
    "sdp": "v=0\r\no=- 4611731400430051336 2 IN IP4 127.0.0.1\r\n…"
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/live/sessions/SESSION_ID/offer",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "type": "offer",
        "sdp": "v=0\r\no=- 4611731400430051336 2 IN IP4 127.0.0.1\r\n…"
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "type": "offer",
  "sdp": "v=0\r\no=- 4611731400430051336 2 IN IP4 127.0.0.1\r\n…"
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/live/sessions/SESSION_ID/offer", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "live_3f9a1c2b7d8e4f60", "object": "live.session", "status": "ringing", "answer": null, "paid_seconds": 60 }
```

## GET /v1/live/sessions/{id}

The call as it stands — the worker's `answer` once it picks up.

### Example request

```bash
curl https://eroq.ai/v1/live/sessions/SESSION_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/live/sessions/SESSION_ID', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/live/sessions/SESSION_ID", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/live/sessions/SESSION_ID", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
"id": "live_3f9a1c2b7d8e4f60", "object": "live.session", "status": "live",
"answer": { "type": "answer", "sdp": "v=0\r\n…" },
"credits_per_minute": 100, "paid_seconds": 120, "seconds": 74.2, "credits_spent": 200,
"end_reason": null, "refunded": false
}
```

## POST /v1/live/sessions/{id}/extend

Buy more time before the bought minutes run out.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `minutes` | integer | no | 1 to 10 (default 1). |

### Example request

```bash
curl https://eroq.ai/v1/live/sessions/SESSION_ID/extend \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "minutes": 1
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/live/sessions/SESSION_ID/extend', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "minutes": 1
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/live/sessions/SESSION_ID/extend",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "minutes": 1
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "minutes": 1
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/live/sessions/SESSION_ID/extend", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "live_3f9a1c2b7d8e4f60", "status": "live", "paid_seconds": 180, "credits_spent": 300, "credits_remaining": 1500 }
```

## POST /v1/live/sessions/{id}/end

Hang up. A call that never connected gives its minute back.

### Example request

```bash
curl -X POST https://eroq.ai/v1/live/sessions/SESSION_ID/end \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/live/sessions/SESSION_ID/end', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post("https://eroq.ai/v1/live/sessions/SESSION_ID/end", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/live/sessions/SESSION_ID/end", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{ "id": "live_3f9a1c2b7d8e4f60", "status": "ended", "seconds": 131.5, "end_reason": "hangup", "refunded": false }
```

---
Canonical: https://eroq.ai/docs/live · Index for agents: https://eroq.ai/llms.txt · OpenAPI: https://eroq.ai/openapi.json
