> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Send your first Context Aware ASR transcription request.

This guide shows the beta API flow for generating a context-aware transcript.

## 1. Use the beta endpoint

Use the VoiceOS beta API endpoint:

```text theme={null}
https://beta.api.voiceos.com
```

## 2. (Optional) Prepare context

Use a chat-style message stack when you want better recognition for domain terms.\
If you do not need context, you can skip `messages` entirely and send only `file`.

```json theme={null}
[
  {
    "role": "system",
    "content": "You are helping inside a TypeScript codebase."
  },
  {
    "role": "user",
    "content": "The relevant files are SessionStreamService.ts and contextAwareTranscription.ts. The env var is VOICEOS_TEAM_API_KEY."
  }
]
```

## 3. Send audio

<CodeGroup>
  ```bash cURL theme={null}
  curl https://beta.api.voiceos.com/v1/audio/transcriptions \
    -H "Authorization: Bearer vos_..." \
    -F "file=@sample.mp3" \
    -F 'messages=[{"role":"system","content":"You are helping inside a TypeScript codebase."},{"role":"user","content":"The relevant files are SessionStreamService.ts and contextAwareTranscription.ts. The env var is VOICEOS_TEAM_API_KEY."}]' \
    -F 'languages="en"' \
    -F 'response_format=json'
  ```

  ```js Node theme={null}
  import { readFile } from "node:fs/promises";

  const audio = await readFile("sample.mp3");
  const form = new FormData();

  form.append("file", new Blob([audio], { type: "audio/mpeg" }), "sample.mp3");
  form.append(
    "messages",
    JSON.stringify([
      {
        role: "system",
        content: "You are helping inside a TypeScript codebase."
      },
      {
        role: "user",
        content:
          "The relevant files are SessionStreamService.ts and contextAwareTranscription.ts. The env var is VOICEOS_TEAM_API_KEY."
      }
    ])
  );
  form.append("languages", JSON.stringify("en"));
  form.append("response_format", "json");

  const response = await fetch("https://beta.api.voiceos.com/v1/audio/transcriptions", {
    method: "POST",
    headers: {
      Authorization: "Bearer vos_..."
    },
    body: form
  });

  console.log(await response.json());
  ```

  ```python Python theme={null}
  import json
  import requests

  messages = [
      {"role": "system", "content": "You are helping inside a TypeScript codebase."},
      {
          "role": "user",
          "content": "The relevant files are SessionStreamService.ts and contextAwareTranscription.ts. The env var is VOICEOS_TEAM_API_KEY.",
      },
  ]

  with open("sample.mp3", "rb") as audio:
      response = requests.post(
          "https://beta.api.voiceos.com/v1/audio/transcriptions",
          headers={"Authorization": "Bearer vos_..."},
          files={"file": ("sample.mp3", audio, "audio/mpeg")},
          data={
              "messages": json.dumps(messages),
              "languages": json.dumps("en"),
              "response_format": "json",
          },
      )

  print(response.json())
  ```
</CodeGroup>

## 4. Read the response

```json theme={null}
{
  "text": "Please open SessionStreamService.ts and update the VOICEOS_TEAM_API_KEY inside contextAwareTranscription.ts."
}
```

<Tip>
  Use `text` as the product-ready transcript output.
</Tip>