---
title: "Real-time API Reference"
section: "Real-time translation"
order: 1
sidebarLabel: "API Reference"
---

## Authentication

All API requests require authentication using a Bearer token in the `Authorization` header.

<div class="docs-transcript not-prose">
  <div class="docs-transcript__title">Authorization header</div>
  <div class="docs-transcript__body" style="font-family: var(--font-mono); white-space: pre-wrap;">
    Authorization: Bearer &lt;your-api-token&gt;
  </div>
</div>

**Base URL:** `https://api.startpinch.com`

## Endpoints

### Create Translation Session

Creates a new real-time translation session and returns connection credentials.

<div
  class="docs-endpoint not-prose"
  data-docs-endpoint
  data-method="POST"
  data-path="/api/beta1/session"
  data-default-body='{"source_language":"en-US","target_language":"es-ES","voice_type":"clone"}'
>
  <div class="docs-endpoint__head">
    <span class="docs-endpoint__method docs-endpoint__method--post">POST</span>
    <code class="docs-endpoint__path">/api/beta1/session</code>
    <button type="button" class="docs-endpoint__toggle" data-docs-endpoint-tryit>Try it</button>
  </div>
  <div class="docs-endpoint__panel" hidden data-docs-endpoint-panel>
    <div class="docs-endpoint__hint">Playground: enter your API key + fields below, then send a real request and inspect the JSON response.</div>
    <div class="docs-endpoint__grid">
      <label class="docs-endpoint__field">
        <span class="docs-endpoint__label">Base URL</span>
        <input class="docs-endpoint__input" type="text" value="https://api.startpinch.com" placeholder="https://api.startpinch.com" data-docs-endpoint-baseurl />
      </label>
      <label class="docs-endpoint__field docs-endpoint__field--wide">
        <span class="docs-endpoint__label">Bearer token</span>
        <input class="docs-endpoint__input" type="password" placeholder="Paste your API token" data-docs-endpoint-token />
      </label>
      <label class="docs-endpoint__field">
        <span class="docs-endpoint__label">source_language</span>
        <input class="docs-endpoint__input" type="text" value="en-US" data-docs-endpoint-field="source_language" />
      </label>
      <label class="docs-endpoint__field">
        <span class="docs-endpoint__label">target_language</span>
        <input class="docs-endpoint__input" type="text" value="es-ES" data-docs-endpoint-field="target_language" />
      </label>
      <label class="docs-endpoint__field">
        <span class="docs-endpoint__label">voice_type</span>
        <select class="docs-endpoint__input" data-docs-endpoint-field="voice_type">
          <option value="clone" selected>clone</option>
          <option value="female">female</option>
          <option value="male">male</option>
        </select>
      </label>
    </div>
    <div class="docs-endpoint__actions">
      <button type="button" class="docs-endpoint__send" data-docs-endpoint-send disabled>Send</button>
      <button type="button" class="docs-endpoint__reset" data-docs-endpoint-reset>Reset</button>
    </div>
    <div class="docs-endpoint__result">
      <div class="docs-endpoint__resultbar">
        <div class="docs-endpoint__resultmeta">
          <span class="docs-endpoint__status" data-docs-endpoint-status>Ready</span>
          <span class="docs-endpoint__url" data-docs-endpoint-url></span>
        </div>
        <button type="button" class="docs-endpoint__copy" aria-label="Copy response" data-docs-endpoint-copy></button>
      </div>
      <pre class="docs-endpoint__pre" aria-label="Response"><code data-docs-endpoint-output>{
  "url": "wss://…",
  "token": "…",
  "room_name": "api-…"
}</code></pre>
    </div>
  </div>
</div>

### Request Headers

| Header | Value | Required |
| --- | --- | --- |
| `Authorization` | `Bearer <your-api-token>` | Yes |
| `Content-Type` | `application/json` | Yes |

### Request Body

<div class="docs-tabbed not-prose" data-docs-tabbed>
  <div class="docs-tabbed__bar">
    <div class="docs-tabbed__tabs" role="tablist" aria-label="Request body">
      <button type="button" class="docs-tabbed__tab is-active" data-tab="schema" aria-selected="true">JSON schema</button>
      <button type="button" class="docs-tabbed__tab" data-tab="example" aria-selected="false">Example request</button>
    </div>
    <button type="button" class="docs-tabbed__copy" aria-label="Copy JSON" data-docs-tabbed-copy></button>
  </div>
  <div class="docs-tabbed__panel is-active" data-panel="schema">
    <pre><code class="language-json">{
  "source_language": "string",
  "target_language": "string",
  "voice_type": "string"
}</code></pre>
  </div>
  <div class="docs-tabbed__panel" data-panel="example" hidden>
    <pre><code class="language-json">{
  "source_language": "en-US",
  "target_language": "es-ES",
  "voice_type": "clone"
}</code></pre>
  </div>
</div>

**Parameters:**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `source_language` | string | Yes | Source language code hint (e.g., `"en-US"`) |
| `target_language` | string | Yes | Target language code (e.g., `"es-ES"`) |
| `voice_type` | string | No | Voice: `"clone"` or `"female"` or `"male"` (default: `"clone"`) |

### Response

<div class="docs-tabbed not-prose" data-docs-tabbed>
  <div class="docs-tabbed__bar">
    <div class="docs-tabbed__tabs" role="tablist" aria-label="Response">
      <button type="button" class="docs-tabbed__tab is-active" data-tab="schema" aria-selected="true">200 JSON schema</button>
      <button type="button" class="docs-tabbed__tab" data-tab="example" aria-selected="false">Example response</button>
    </div>
    <button type="button" class="docs-tabbed__copy" aria-label="Copy JSON" data-docs-tabbed-copy></button>
  </div>
  <div class="docs-tabbed__panel is-active" data-panel="schema">
    <pre><code class="language-json">{
  "url": "string",
  "token": "string",
  "room_name": "string"
}</code></pre>
  </div>
  <div class="docs-tabbed__panel" data-panel="example" hidden>
    <pre><code class="language-json">{
  "url": "wss://pinch-prod-interpreter-jgw70la3.livekit.cloud",
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiQVBJIENsaWVudCIsInZpZGVvIjp7InJvb21Kb2luIjp0cnVlLCJyb29tIjoiYXBpLTQ0YTcwMTk2IiwiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZSwiY2FuVXBkYXRlT3duTWV0YWRhdGEiOnRydWV9LCJpc3MiOiJBUEl1TU1wN0J4dGROSDkiLCJleHAiOjE3NzA4NjcxMDcsIm5iZiI6MCwic3ViIjoiY2xpZW50LTQ0YTcwMTk2In0.2UpXCF-eLULMBNUvXCqT_oOwVUmshVvjJVxGVa6FihE",
  "room_name": "api-44a70196"
}</code></pre>
  </div>
</div>

**Response Fields:**

| Field | Type | Description |
| --- | --- | --- |
| `url` | string | URL for connection |
| `token` | string | JWT token for authenticating to room |
| `room_name` | string | Unique room identifier (format: `api-<random-id>`) |

### Example Requests

**JavaScript (Fetch)**

```jsx
const response = await fetch('https://api.startpinch.com/api/beta1/session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your-api-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_language: 'en-US',
    target_language: 'es-ES',
    voice_type: 'clone'
  })
});

const session = await response.json();
console.log(session);
```

### Error Responses

<div class="docs-tabbed not-prose" data-docs-tabbed>
  <div class="docs-tabbed__bar">
    <div class="docs-tabbed__tabs" role="tablist" aria-label="Error responses">
      <button type="button" class="docs-tabbed__tab is-active" data-tab="400" aria-selected="true">400</button>
      <button type="button" class="docs-tabbed__tab" data-tab="401" aria-selected="false">401</button>
      <button type="button" class="docs-tabbed__tab" data-tab="429" aria-selected="false">429</button>
      <button type="button" class="docs-tabbed__tab" data-tab="500" aria-selected="false">500</button>
    </div>
    <button type="button" class="docs-tabbed__copy" aria-label="Copy JSON" data-docs-tabbed-copy></button>
  </div>
  <div class="docs-tabbed__panel is-active" data-panel="400">
    <pre><code class="language-json">{
  "error": {
    "code": "invalid_language",
    "message": "Unsupported target language: xx-XX"
  }
}</code></pre>
  </div>
  <div class="docs-tabbed__panel" data-panel="401" hidden>
    <pre><code class="language-json">{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or expired API token"
  }
}</code></pre>
  </div>
  <div class="docs-tabbed__panel" data-panel="429" hidden>
    <pre><code class="language-json">{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests"
  }
}</code></pre>
  </div>
  <div class="docs-tabbed__panel" data-panel="500" hidden>
    <pre><code class="language-json">{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred"
  }
}</code></pre>
  </div>
</div>

## Data Messages

Transcript data is published via data channel using the `DataReceived` event.

The system publishes two types of transcripts:

### Original Transcript

The recognized speech in the source language:

```json
{
  "type": "original_transcript",
  "text": "Hello, how are you?",
  "timestamp": 1770933604.048,
  "is_final": true,
  "language_detected": "en-US",
}
```

### Translated Transcript

The translated text in the target language:

```json
{
  "type": "translated_transcript",
  "text": "Hola, ¿cómo estás?",
  "timestamp": 1770933604.945,
  "is_final": true,
  "language_detected": "en-US",
}
```

### Interim vs final results

**Interim results (`is_final: false`)**

- Partial transcripts generated as speech is detected
- Only for original_transcript messages, and some languages do not support interim
- May change as more audio is processed
- Useful for displaying real-time feedback

**Final results (`is_final: true`)**

- Complete, stable transcripts
- translated_transcript messages are always final

### Language detection

- Transcript messages include `language_detected` (for example, `en-US`) so clients can see what language the model identified for that segment.
- Represents the end of a speech segment

### Transcript segmentation

The system intelligently segments speech into translatable units. It identifies natural sentence boundaries and waits for speech pauses to finalize segments.

Example:

<div class="docs-transcript not-prose">
  <div class="docs-transcript__title">EXAMPLE</div>
  <div class="docs-transcript__body" style="font-family: var(--font-mono); white-space: pre-wrap;">[interim] "One has red color and other has yellow so"
[interim] "One has red colour and other has yellow. So, I really..."
[final]   "One has red colour and other has yellow."
[final]   "So, I really love these colours."</div>
</div>

---

## Voice Types

Three voice options are available:

- **`clone`**: Your own voice
- **`female`**: Female voice synthesis
- **`male`**: Male voice synthesis

The default voice type is **`clone`**.