# curl example

> Create a session with one curl command. The script, the settings and what the answer holds.

Source: https://docs.voice.kheelona.com/examples/curl/

The shortest way to see the API answer: one `POST /v1/sessions` with curl.

```sh
export KHEELONA_API_KEY=kv_live_…
./create-session.sh
```

It prints the session: the `session_id`, a single-use `client_secret`, the `connect` addresses, the pinned voice and the
limits. Give the secret to a client within its lifetime, about a minute. The Node, Python and browser examples are
clients.

## Settings

| Variable | Default | Meaning |
|---|---|---|
| `KHEELONA_API_KEY` | none (the script exits with a hint when missing) | Your API key |
| `KHEELONA_API_URL` | `https://api.voice.kheelona.com` | The API |
| `KHEELONA_VOICE_ID` | `lumi-dragon` | The voice |

## Notes

- The key goes to curl on **standard input** (`-H @-`), never as an argument, so it is not in a process list or in your
  shell history. It needs curl 7.76 or newer and `uuidgen`.
- `Idempotency-Key` is one fresh UUID per session. Repeating a request with the same key returns the same session with a
  new client secret. See [Sessions](https://docs.voice.kheelona.com/concepts/sessions.md).
- The answer holds a client secret. Don't paste it into chat, tickets or logs.
- To end a session that you created and never connected: `POST /v1/sessions/{id}/end` with the same `Authorization`
  header.

## The file

**curl/create-session.sh**

```bash title="create-session.sh"
#!/usr/bin/env bash
# Creates a Kheelona Voice session with curl and prints the answer (JSON: session_id, client_secret, connect, ...).
#   KHEELONA_API_KEY=... ./create-session.sh
# The key reaches curl on its standard input, never on the command line, so it is in no process list.
# The answer holds a single-use client secret: treat it like a password, and never log it.
set -euo pipefail

: "${KHEELONA_API_KEY:?Set KHEELONA_API_KEY to your API key (from the console)}"

API_URL="${KHEELONA_API_URL:-https://api.voice.kheelona.com}"
VOICE_ID="${KHEELONA_VOICE_ID:-lumi-dragon}"

# One Idempotency-Key per logical session: repeating the request with the same key returns the same session.
printf 'Authorization: Bearer %s\n' "$KHEELONA_API_KEY" | curl -sS --fail-with-body \
  -H @- \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -X POST "$API_URL/v1/sessions" \
  -d "{\"voice_id\": \"$VOICE_ID\", \"languages\": [\"en\", \"hi\"]}"
echo
```

The examples are Kheelona's own and are given to partners privately. Contact the Kheelona team for licensing.