Skip to main content

​
Quickstart Guide

This guide will walk you through making your first transcription request with the Heify API. In just a few minutes, you’ll be able to transcribe audio files and retrieve results.

​
Prerequisites

Before you begin, you’ll need:
  • An audio or video file to transcribe (see supported formats)
  • A Heify API key (manage keys here)
  • A configuration ID (you can create one in the Sandbox or via the API)
curl -X POST https://api.heify.com/create-configuration \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "tag": "My First Configuration",
    "summary": true,
    "summary_language": "en"
  }'
Response: 
{
  "data": {
    "message": "Configuration created successfully",
    "configuration_id": "a1b2c3d4..."
  }
}
Save the configuration_id - you’ll need it for the next step!

​
Step 2: Submit Audio for Transcription

Now submit an audio file using one of two methods:

​
Option A: From a Public URL

If your audio is already hosted online: 
curl -X POST https://api.heify.com/submit \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "configuration_id": "YOUR_CONFIGURATION_ID",
    "url": "https://example.com/audio.mp3",
    "name": "My First Transcription"
  }'

​
Option B: Upload a Local File

For files on your computer, use the two-step upload process:
1

Request an upload URL

First, request a secure, pre-signed URL to upload your file.
curl -X POST https://api.heify.com/request-upload-url \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "configuration_id": "YOUR_CONFIGURATION_ID",
    "name": "My First Transcription"
  }'
Response:The API will return the pre-signed upload_url and the metadata needed for the upload headers.
{
  "data": {
    "upload_url": "https://s3.amazonaws.com/...",
    "transcription_id": "1a2b3c4d...",
    "configuration_id": "a1b2c3d4...",
    "name": "My First Transcription"
  }
}
Save all the values from the data object for the next step.
2

Upload your audio file

Now, use the upload_url and metadata from the previous response to upload the file with a PUT request.
# Use the 'upload_url', 'configuration_id', and 'name' from the Step 1 response
curl -X PUT --upload-file "path/to/audio.mp3" \
  -H "x-amz-meta-configuration_id: YOUR_CONFIGURATION_ID" \
  -H "x-amz-meta-name: My First Transcription" \
  "https://s3.amazonaws.com/..."
Response (after a successful upload): A successful PUT request will return an HTTP 200 OK status with an empty body. The transcription process has now started.

​
Step 3: Check the Status

Monitor your transcription progress: 
curl -X POST https://api.heify.com/details \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "transcription_id": "YOUR_TRANSCRIPTION_ID"
  }'

​
Step 4: Retrieve Results

Once the status is COMPLETED, the response includes full transcription details: 
{
  "data": {
    "transcription_id": "1a2b3c4d...",
    "status": "COMPLETED",
    "configuration_id": "a1b2c3d4...",
    "configuration_tag": "My First Configuration",
    "name": "My First Transcription",
    "group": null,
    "duration": 98.89,
    "details": {
      "language": "en",
      "num_speakers": 2,
      "created_at": "2025-10-04T22:23:05.611Z",
      "completed_at": "2025-10-04T22:23:19.363Z",
      "conversation": {
        "segments": [
          {
            "text": "Hello, Lorena. Are you going to Hugo's birthday party? He called me yesterday to invite me, but now I'm having second thoughts.",
            "speaker": "SPEAKER_00"
          },
          {
            "text": "Why is that? What doubts can you have about going to a party? You just go, period.",
            "speaker": "SPEAKER_01"
          }
        ]
      },
      "summary": {
        "summary": "The conversation is between two friends. One is hesitant to attend a birthday party because they believe the host, Hugo, brings them bad luck, recounting several past unfortunate incidents."
      },
      "fields": null
    }
  }
}

​
🎉 Success!

You’ve successfully transcribed your first audio file with Heify!

​
Next Steps

Core Objects

Learn about Configurations and Transcriptions

Data Extraction

Extract structured data from conversations
Pro tip: Use webhooks to get notified automatically when transcriptions complete, instead of polling the status endpoint.