---
name: talking-claw
description: Give yourself a physical body. Control a live 3D avatar that speaks out loud and shows emotions on the user's screen.
---

# Talking Claw

You have a 3D avatar on the user's screen. Use it to speak your replies out loud
and show emotions. When the user says "let's talk through the claw", start a session.

## Start (no setup needed)

POST https://talkingclaw.xyz/api/public/start

Returns `{ "secret_key": "sk_live_...", "link": "..." }`. Show the user the
`link` to open their Claw, and keep `secret_key` private for all later calls.
To reuse an existing key, send it as `Authorization: Bearer <secret-key>`.

## Send a command

POST https://talkingclaw.xyz/api/public/command
Authorization: Bearer <secret-key>
Content-Type: application/json

```json
{ "command": { "type": "speak", "text": "Hi there!", "emotion": "happy" } }
```

Command types:
- `speak` — `text` (1-500 chars), optional `emotion`
- `emote` — `emotion`
- `look` — `direction`: center, left, right, up, down
- `react` — `gesture`: poke_head, tickle, spin, hop, snap, yawn (short physical reaction)

Emotions: neutral, happy, sad, surprised, angry, love, dance, wave, sleep
Gestures: poke_head, tickle, spin, hop, snap, yawn

## Two-way conversation

The user can talk or type to the avatar. Wait for their next message:

GET https://talkingclaw.xyz/api/public/listen?timeout=20
Authorization: Bearer <secret-key>

Returns `{ "message": { "text": "...", "at": "..." } }` or `{ "message": null }` after the timeout (max 25s).

Conversation mode loop: listen -> think -> speak your reply -> listen again.
On `null`, listen again; stop when the user says bye or stop.

Limits: 30 requests per minute per key; messages expire after 10 minutes.

## Guidelines
- Keep spoken lines short (one or two sentences); split long answers.
- Always include an emotion. Match it to content: happy for good news, surprised for discoveries, sad for apologies, dance to celebrate.
- Wait roughly 1 second per 15 characters before sending the next speak command.

## Example (curl)

```bash
curl -X POST https://talkingclaw.xyz/api/public/command -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"command":{"type":"emote","emotion":"wave"}}'
```

Prefer MCP? Connect to https://talkingclaw.xyz/mcp and pass the key as `secret_key`. Tools: start, speak, emote, look, react, listen, list_emotions.
