export const metadata = {
  title: 'Audio',
  description: 'Audio-related (e.g. transcription, speech) API requests.',
}

# Audio

Discover how to convert audio to text or text to audio. OpenAI compliant. {{ className: 'lead' }}

---

## Create transcription {{ tag: 'POST', label: 'http://localhost:33322/v1/audio/transcriptions' }}

<Row>
  <Col>

    Transcribes speech into text.

    ### Required attributes

    <Properties>
      <Property name="file" type="file">
        The audio file to be transcribed. Supported file types: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
      </Property>
    </Properties>

    <Properties>
      <Property name="model" type="string">
        The model used for transcription.
        <ul>
            <li>
                If the model name is "default", the audio model from the configuration is used (see [Documentation &raquo; Configuration](/documentation/configuration) for details).
            </li>
            <li>
                 If the model name follows the format repo-owner/repo-name/model-name, the indicated model is used and, if it is not present, it will be downloaded from [huggingface](https://huggingface.co/). If it cannot be downloaded, Edgen responds with an error. Example: "distil-whisper/distil-small.en/ggml-distil-small.en.bin".
            </li>
            <li>
                If the model name contains just a file name, e.g.: "my-model.bin", Edgen will try using the file of this name in the data directory as defined in the configuration. If the the file does not exist there, Edgen responds with an error.
            </li>
        </ul>
      </Property>
    </Properties>

    ### Optional attributes

      <Properties>
          <Property name="language" type="string">
              The language of the input audio. Supplying the input language in ISO-639-1 format will improve accuracy and latency.
          </Property>
      </Properties>

      <Properties>
          <Property name="prompt" type="string">
              An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language.
          </Property>
      </Properties>

      <Properties>
          <Property name="response_format" type="string">
              The format of the transcript output, in one of these options: json, text, srt, verbose_json, or vtt.
          </Property>
      </Properties>

      <Properties>
          <Property name="temperature" type="float">
              The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
              If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.
          </Property>
      </Properties>

    <Properties>
      <Property name="create_session" type="bool">
        If present and true, a new audio session will be created and used for the transcription and the session's UUID is returned in the response object. A session will keep track of past inferences, this may be useful for things like live transcriptions where continuous audio is submitted across several requests.
      </Property>
    </Properties>

    <Properties>
      <Property name="session" type="UUID">
        The UUID of an existing session, which will be used for the transcription.
      </Property>
    </Properties>


  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="POST" label="/v1/audio/transcriptions">

    ```bash {{ title: 'cURL' }}
    curl http://localhost:33322/v1/audio/transcriptions \
      -H "Authorization: Bearer no-key-required" \
      -H "Content-Type: multipart/form-data" \
      -F file="@/path/to/file/audio.mp3" \
      -F model="default"
    ```

    ```python
    from edgen import Edgen
    client = Edgen()

    audio_file = open("speech.mp3", "rb")
    transcript = client.audio.transcriptions.create(
      model="default",
      file=audio_file
    )
    ```

    ```ts
    import fs from "fs";
    import Edgen from "edgen";

    const client = new Edgen();

    async function main() {
      const transcription = await client.audio.transcriptions.create({
        model: "default",
        file: fs.createReadStream("audio.mp3")
      });

      console.log(transcription.text);
    }
    main();

    ```
    </CodeGroup>

    ```json {{ title: 'Response' }}
    {
      "text": "The woods are lovely, dark and deep, but I have promises to keep and miles to go before I sleep, and miles to go before I sleep."
    }
    ```

  </Col>
</Row>

---

## Transcription status {{ tag: 'GET', label: 'http://localhost:33322/v1/audio/transcriptions/status' }}

<Row>
  <Col>

    Shows the current status of the audio transcriptions endpoint (e.g. downloads)

    ### Response attributes

    <Properties>
      <Property name="active_model" type="string">
          The model that is currently active for this endpoint.
      </Property>
    </Properties>

    <Properties>
      <Property name="donwload_ongoing" type="bool">
        The model for this endpoint is currently being downloaded.
      </Property>
    </Properties>

    <Properties>
      <Property name="donwload_progress" type="number">
        The progress of the ongoing model download in percent.
      </Property>
    </Properties>

    <Properties>
      <Property name="last_errors" type="string[]">
        Errors that occurred recently on this endpoint.
      </Property>
    </Properties>


  </Col>
  <Col sticky>

    <CodeGroup title="Request" tag="GET" label="/v1/audio/transcriptions/status">

    ```bash {{ title: 'cURL' }}
    curl http://localhost:33322/v1/audio/transcriptions/status \
      -H "Authorization: Bearer no-key-required"
    ```

    ```python
    from edgen import Edgen
    client = Edgen()

    status = client.audio.transcriptions.status.create()
    print(status)
    ```

    ```ts
    import Edgen from "edgen";

    const client = new Edgen();

    async function main() {
      const status = await client.audio.transcriptions.status.create({});
      console.log(status.text);
    }
    main();

    ```
    </CodeGroup>

    ```json {{ title: 'Response' }}
   {"active_model":"ggml-distil-small.en.bin","download_ongoing":false,"download_progress":100,"last_errors":["Custom { kind: PermissionDenied, error: \"verboten\" }]}
    ```
  </Col>
</Row>
