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

# Audio

Pass-through to the provider's audio endpoint (speech, transcription, translation). Request and response bodies follow the standard OpenAI Audio API schema. The provider is inferred from the model name (e.g. `tts-1`, `whisper-1` route to OpenAI).

<Note>
  Audio requests pass through to your provider and work today. They are not yet counted toward your cost totals. Full cost tracking for audio is coming soon.
</Note>

<Note>
  Audio supports both JSON (`application/json`) and multipart/form-data bodies. Use JSON for text-to-speech (TTS) requests and multipart/form-data for transcription and translation (Whisper) requests, following the standard OpenAI Audio API schema.
</Note>

## Headers

<ParamField header="X-Toolken-Key" type="string" required>
  Your Toolken API key. Validated by the gateway and stripped before forwarding.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your provider key in Bearer format (BYOK), e.g. `Bearer sk-...`. Forwarded untouched, never stored.
</ParamField>

<ParamField header="X-Toolken-Metadata" type="string">
  Primary attribution channel. JSON object of key-value pairs (e.g. `{"agent":"research-agent","customer_id":"cust_abc"}`). Each key becomes a groupable dimension in the dashboard.
</ParamField>

<ParamField header="X-Toolken-Metadata-*" type="string">
  Flat-header shorthand. `X-Toolken-Metadata-Agent: research-agent` writes metadata key `agent`. Equivalent to sending the same key in `X-Toolken-Metadata`.
</ParamField>

<ParamField header="X-Toolken-Metadata-Feature" type="string">
  Sets the `feature` metadata key. Use to group costs by agent name, workflow, UI surface, or job type.
</ParamField>

<ParamField header="X-Toolken-Metadata-Customer-Id" type="string">
  Sets the `customer_id` metadata key. Use to attribute costs to an end-customer, org slug, or account ID.
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Audio model identifier (e.g. `tts-1` for speech, `whisper-1` for transcription/translation).
</ParamField>

Additional fields follow the standard OpenAI Audio API schema. For speech, include `input` (text to synthesize) and `voice`. For transcription and translation, send multipart/form-data with a `file` field.

## Response

Speech requests return audio bytes (`audio/mpeg`). Transcription and translation requests return a JSON object with a `text` field. The response is forwarded verbatim from the provider.

<RequestExample>
  ```bash cURL (TTS) theme={null}
  curl https://gateway.toolken.ai/v1/audio/speech \
    -H "X-Toolken-Key: tk_live_..." \
    -H "Authorization: Bearer sk-..." \
    -H "Content-Type: application/json" \
    -d '{"model": "tts-1", "input": "Hello from Toolken.", "voice": "alloy"}' \
    --output speech.mp3
  ```

  ```bash cURL (Transcription) theme={null}
  curl https://gateway.toolken.ai/v1/audio/transcriptions \
    -H "X-Toolken-Key: tk_live_..." \
    -H "Authorization: Bearer sk-..." \
    -F model=whisper-1 \
    -F file=@audio.mp3
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://gateway.toolken.ai/v1",
      api_key="sk-...",
      default_headers={"X-Toolken-Key": "tk_live_..."},
  )

  # Text-to-speech
  response = client.audio.speech.create(
      model="tts-1",
      voice="alloy",
      input="Hello from Toolken.",
  )
  response.stream_to_file("speech.mp3")
  ```

  ```javascript Node theme={null}
  import OpenAI from "openai";
  import fs from "fs";

  const client = new OpenAI({
    baseURL: "https://gateway.toolken.ai/v1",
    apiKey: "sk-...",
    defaultHeaders: { "X-Toolken-Key": "tk_live_..." },
  });

  // Text-to-speech
  const mp3 = await client.audio.speech.create({
    model: "tts-1",
    voice: "alloy",
    input: "Hello from Toolken.",
  });
  const buffer = Buffer.from(await mp3.arrayBuffer());
  fs.writeFileSync("speech.mp3", buffer);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (Transcription) theme={null}
  {
    "text": "Hello from Toolken."
  }
  ```
</ResponseExample>