Transcription

Given an audio file, AudioShake will transcribe audio into readable text. This task can also be combined with alignment as a single call. See instructions for that combined task.

Upload a File

You can make a POST request to the /upload/audio-link endpoint. When using this endpoint, you should send a JSON payload that includes a link to the audio file. Alternatively, you can use the more general /upload endpoint for uploading audio files directly. Expect both endpoints to return a JSON payload containing an asset object with an “id”.

Further documentation on uploading files can be found here

Create a Job

Once you have the asset ID, you can create a job request to generate a transcription using the /jobs endpoint. The endpoint accepts a JSON request with the file ID, a callback url, and a metadata object that contains a format and name that maps to the desired output. In the following example, we'll explicitly use transcription:

curl -L -X POST 'https://groovy.audioshake.ai/job/' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <TOKEN>' \
    --data-raw '{
      "metadata": {
        "format": "json",
        "name": "transcription",
        "language": "en"
      },
      "callbackUrl": "https://example.com/webhook/transcription",
      "assetId": "def456"
    }'

Upon successful initiation, the server will reply with an HTTP status code of 200, indicating that everything is OK. The response will include a 'job' object, which contains details about the job that has been started.You can use the provided job ID in two ways:

1. Wait for a callback from AudioShake, which will be sent upon completion or status update of the job.
2. Periodically check the status of the job by polling using the job id.

{
  job: {
    id: "clmgnr10z001oeumub3a9hifc",
    clientId: "<YOUR CLIENT ID>",
    requestId: "clmgnr10z001oeumub3a9hifc",
    metadata: {
      format: "json",
      name: "transcription",
      language: "en"
    },
    callbackUrl: "<YOUR CALLBACK URL>",
    status: "created",
  },
}

Get Job

After you have created a job request, you can retrieve the results by making a GET request to the /jobs/{job_id} endpoint, where job_id is the ID of the job that you created. Here is an example of a curl command that retrieves the results of a job request:

curl --request GET \
    --url https://groovy.audioshake.ai/job/[insert job ID here] \
    --header 'Authorization: Bearer [insert JWT token here]' \
    --header 'Content-Type: application/json'

The server will reply with an HTTP status code of 200 with a response that contains a "job" object.

{
  job: {
    id: "clmgnr10z001oeumub3a9hifc",
    clientId: "<YOUR CLIENT ID>",
    createdAt: "2023-08-01T20:37:06.656Z",
    startedAt: "2023-08-01T20:37:07.839Z",
    updatedAt: "2023-08-01T20:37:28.392Z",
    requestId: "clksrfob8000bf7of6xkscy8m",
    licenseId: "<YOUR LICENSE ID>",
    metadata: {
      format: "json",
      name: "transcription",
      language: "en"
    },
    callbackUrl: "<YOUR CALLBACK URL>",
    status: "completed",
    statusInfo: {},
    sourceAsset: {
      name: "<Your-File.mp3>",
      id: "clmgn7nkg50527f0mulbhwi6z8",
      fileType: "audio/mpeg",
      format: "mp3",
      link: "<LINK TO FILE>",
    },
    outputAssets: [
      {
        name: "transcription.json",
        id: "clksrg52j2319f7of26wleinn",
        fileType: "application/json",
        format: "json",
        link: "<LINK TO GENERATED FILE>",
      },
    ],
  },
}