# Add a speech service of your own

Source: https://docs.vlayers.ai/reference/hosting/create-speech-connection

`POST /v1/connections/speech` · scope `workspace:write`

Adds a voice or transcriber you run. `kind: openai_compatible_voice` is an endpoint that answers OpenAI's `/audio/speech` at an `https` base URL (a voice only). `kind: custom_speech` is your own service over VoiceLayer's WebSocket protocol at a `wss://` address (voice, transcriber or both). The address has to be public: a private or internal address is refused with `endpoint_url_unsafe`. A custom service's signing secret is in the answer once; keep it, your service uses it to check that a call comes from VoiceLayer. Then name the connection's id as `connectionId` on an agent's voice or transcriber.

Requires an API key with the `workspace:write` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | body | "openai_compatible_voice" \| "custom_speech" | yes | One of `openai_compatible_voice`, `custom_speech`. |
| `name` | body | string | yes | A name for the connection. |
| `secret` | body | string | yes | The key or bearer secret the service expects. Stored encrypted and never returned. |
| `url` | body | string | no | custom_speech: the `wss://` address of your service |
| `baseUrl` | body | string | no | openai_compatible_voice: https base URL; `/audio/speech` is appended |
| `model` | body | string | no | openai_compatible_voice: the model name the endpoint expects (default tts-1) |
| `voices` | body | string[] | no | openai_compatible_voice: the voice names the endpoint offers |
| `languages` | body | string[] | no | The languages the service covers, for example `gu-IN`; without them coverage is unknown |
| `region` | body | "in" \| "eu" \| "us" | no | Where the service processes speech, in your own words; the workspace speech region reads it |
| `reportsLanguage` | body | boolean | no | custom_speech: whether the transcriber says the language it heard |
| `budgets` | body | object | no | custom_speech: how long a first result or first audio may take, up to 15 seconds |

## Request

cURL:

```bash
curl -X POST https://api.vlayers.ai/v1/connections/speech \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "custom_speech",
    "name": "Our Gujarati speech service",
    "url": "wss://speech.example.com/vl",
    "secret": "a-long-random-secret",
    "languages": [
      "gu-IN",
      "hi-IN"
    ],
    "region": "in"
  }'
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { connection } = await voicelayer.hosting.createSpeechConnection({
  kind: 'custom_speech',
  name: 'Our Gujarati speech service',
  url: 'wss://speech.example.com/vl',
  secret: 'a-long-random-secret',
  languages: ['gu-IN', 'hi-IN'],
  region: 'in'
});
console.log(connection.id);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.hosting.create_speech_connection(
    kind="custom_speech",
    name="Our Gujarati speech service",
    url="wss://speech.example.com/vl",
    secret="a-long-random-secret",
    languages=["gu-IN", "hi-IN"],
    region="in",
)
print(result.connection.id)
```

## Response `201`

```json
{
  "connection": {
    "id": "0e9d8c7b-6a5f-4e3d-8c1b-0a9f8e7d6c5b",
    "name": "Our Gujarati speech service",
    "provider": "custom-speech",
    "status": "active",
    "metadata": {
      "kind": "custom_speech",
      "baseUrl": "wss://speech.example.com/vl"
    }
  },
  "signingSecret": "vlss_0000000000000000000000000000000000000000000000"
}
```
