Customizing Transcription with Language and Prompt Parameters

Introduction: Why Customize Transcription?

Welcome to the first lesson of the course, where we will explore how to make your audio transcriptions smarter and more accurate by customizing the transcription process. In many real-world situations, audio files can be in different languages or contain specific topics, names, or jargon. By customizing the transcription settings, you can help the model understand your audio better and produce more accurate results. In this lesson, you will learn how to use custom parameters — specifically, the language and prompt options — when transcribing audio with OpenAI GPT-4o Mini in Java using direct HTTP requests. These options allow you to tell the model what language to expect and give it extra context about the audio, which can be very helpful for meetings, interviews, or technical discussions.

Recall: Basic Transcription with HTTP Requests

Before we dive into custom parameters, let's remind ourselves how a basic transcription works using direct HTTP requests. In a simple setup, you provide an audio file to the model via a multipart/form-data POST request, and it returns the text it hears using default settings. For example, in previous lessons, you might have seen code like this: Java import java.io.File; import java.io.IOException; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; // Basic transcription request // Create a unique boundary to separate form data parts String boundary = "----boundary" + System.currentTimeMillis(); // Build the multipart form data with audio file byte[] formData = buildBasicFormData(audioFile, boundary); // Create HTTP POST request to the transcription endpoint HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(baseUrl + "/v1/audio/transcriptions")) .header("Authorization", "Bearer " + apiKey) // API authentication .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Specify form data type .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Send form data as request body .build(); // Send the request and get the response HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); This code sends an audio file to the model and returns the transcribed text. By default, the model tries to detect the language and does not use any extra context.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

XML

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>
<dependency>
    <groupId>io.github.cdimascio</groupId>
    <artifactId>dotenv-java</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>
<dependency>
    <groupId>io.github.cdimascio</groupId>
    <artifactId>dotenv-java</artifactId>
    <version>3.0.0</version>
</dependency>

gradle

implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2'
implementation 'io.github.cdimascio:dotenv-java:3.0.0'

implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2'
implementation 'io.github.cdimascio:dotenv-java:3.0.0'

Java

// Environment variable loading
import io.github.cdimascio.dotenv.Dotenv;
// JSON parsing and handling
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
// File operations
import java.io.File;
import java.io.IOException;
// HTTP client functionality
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// File reading operations
import java.nio.file.Files;

// Environment variable loading
import io.github.cdimascio.dotenv.Dotenv;
// JSON parsing and handling
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
// File operations
import java.io.File;
import java.io.IOException;
// HTTP client functionality
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// File reading operations
import java.nio.file.Files;

Java

// Load environment variables from .env file (ignores if file doesn't exist)
Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
// Get the OpenAI API key from environment variables
String apiKey = dotenv.get("OPENAI_API_KEY");
// Get the base URL for API requests (allows for custom endpoints)
String baseUrl = dotenv.get("OPENAI_BASE_URL");
// Create HTTP client for making API requests
HttpClient httpClient = HttpClient.newHttpClient();
// Create JSON parser for handling API responses
ObjectMapper objectMapper = new ObjectMapper();

// Load environment variables from .env file (ignores if file doesn't exist)
Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
// Get the OpenAI API key from environment variables
String apiKey = dotenv.get("OPENAI_API_KEY");
// Get the base URL for API requests (allows for custom endpoints)
String baseUrl = dotenv.get("OPENAI_BASE_URL");
// Create HTTP client for making API requests
HttpClient httpClient = HttpClient.newHttpClient();
// Create JSON parser for handling API responses
ObjectMapper objectMapper = new ObjectMapper();

Java

// Create a File object pointing to the audio file to transcribe
File audioFile = new File("recording.wav");

// Create a File object pointing to the audio file to transcribe
File audioFile = new File("recording.wav");

Java

private byte[] buildFormData(File audioFile, String boundary, String language, String prompt) throws IOException {
    // StringBuilder to construct the multipart form data structure
    StringBuilder formData = new StringBuilder();
    
    // Add model field - specifies which transcription model to use
    formData.append("--").append(boundary).append("\r\n");
    formData.append("Content-Disposition: form-data; name=\"model\"\r\n\r\n");
    formData.append("gpt-4o-mini-transcribe\r\n");
    
    // Add language field only if provided - helps model focus on specific language
    if (language != null && !language.isEmpty()) {
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"language\"\r\n\r\n");
        formData.append(language).append("\r\n");
    }
    
    // Add prompt field only if provided - gives context to improve transcription accuracy
    if (prompt != null && !prompt.isEmpty()) {
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"prompt\"\r\n\r\n");
        formData.append(prompt).append("\r\n");
    }
    
    // Add file field with proper headers for audio file upload
    formData.append("--").append(boundary).append("\r\n");
    formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(audioFile.getName()).append("\"\r\n");
    formData.append("Content-Type: audio/wav\r\n\r\n");
    
    // Convert form data structure to bytes
    byte[] formBytes = formData.toString().getBytes();
    // Read the actual audio file content as bytes
    byte[] fileBytes = Files.readAllBytes(audioFile.toPath());
    // Create the final boundary marker to end the multipart data
    byte[] endBytes = ("\r\n--" + boundary + "--\r\n").getBytes();
    
    // Combine all parts: form headers + file content + end boundary
    byte[] result = new byte[formBytes.length + fileBytes.length + endBytes.length];
    System.arraycopy(formBytes, 0, result, 0, formBytes.length);
    System.arraycopy(fileBytes, 0, result, formBytes.length, fileBytes.length);
    System.arraycopy(endBytes, 0, result, formBytes.length + fileBytes.length, endBytes.length);
    
    return result;
}

private byte[] buildFormData(File audioFile, String boundary, String language, String prompt) throws IOException {
    // StringBuilder to construct the multipart form data structure
    StringBuilder formData = new StringBuilder();
    
    // Add model field - specifies which transcription model to use
    formData.append("--").append(boundary).append("\r\n");
    formData.append("Content-Disposition: form-data; name=\"model\"\r\n\r\n");
    formData.append("gpt-4o-mini-transcribe\r\n");
    
    // Add language field only if provided - helps model focus on specific language
    if (language != null && !language.isEmpty()) {
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"language\"\r\n\r\n");
        formData.append(language).append("\r\n");
    }
    
    // Add prompt field only if provided - gives context to improve transcription accuracy
    if (prompt != null && !prompt.isEmpty()) {
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"prompt\"\r\n\r\n");
        formData.append(prompt).append("\r\n");
    }
    
    // Add file field with proper headers for audio file upload
    formData.append("--").append(boundary).append("\r\n");
    formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(audioFile.getName()).append("\"\r\n");
    formData.append("Content-Type: audio/wav\r\n\r\n");
    
    // Convert form data structure to bytes
    byte[] formBytes = formData.toString().getBytes();
    // Read the actual audio file content as bytes
    byte[] fileBytes = Files.readAllBytes(audioFile.toPath());
    // Create the final boundary marker to end the multipart data
    byte[] endBytes = ("\r\n--" + boundary + "--\r\n").getBytes();
    
    // Combine all parts: form headers + file content + end boundary
    byte[] result = new byte[formBytes.length + fileBytes.length + endBytes.length];
    System.arraycopy(formBytes, 0, result, 0, formBytes.length);
    System.arraycopy(fileBytes, 0, result, formBytes.length, fileBytes.length);
    System.arraycopy(endBytes, 0, result, formBytes.length + fileBytes.length, endBytes.length);
    
    return result;
}

Java

public String transcribeWithOptions(File audioFile, String language, String prompt) throws Exception {
    // Generate unique boundary for this request using current timestamp
    String boundary = "----boundary" + System.currentTimeMillis();
    // Build the multipart form data with all parameters
    byte[] formData = buildFormData(audioFile, boundary, language, prompt);
    
    // Create HTTP POST request to the transcription API endpoint
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(baseUrl + "/v1/audio/transcriptions"))
        .header("Authorization", "Bearer " + apiKey) // Authenticate with API key
        .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Specify content type
        .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Send form data as request body
        .build();
        
    // Send the request and receive the response
    HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    
    // Check if the request was successful (HTTP 200)
    if (response.statusCode() == 200) {
        // Parse the JSON response safely using Jackson
        JsonNode jsonResponse = objectMapper.readTree(response.body());
        // Extract the transcribed text from the "text" field
        return jsonResponse.get("text").asText();
    } else {
        // Handle API errors by throwing an exception with error details
        throw new RuntimeException("API request failed: " + response.body());
    }
}

public String transcribeWithOptions(File audioFile, String language, String prompt) throws Exception {
    // Generate unique boundary for this request using current timestamp
    String boundary = "----boundary" + System.currentTimeMillis();
    // Build the multipart form data with all parameters
    byte[] formData = buildFormData(audioFile, boundary, language, prompt);
    
    // Create HTTP POST request to the transcription API endpoint
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(baseUrl + "/v1/audio/transcriptions"))
        .header("Authorization", "Bearer " + apiKey) // Authenticate with API key
        .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Specify content type
        .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Send form data as request body
        .build();
        
    // Send the request and receive the response
    HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    
    // Check if the request was successful (HTTP 200)
    if (response.statusCode() == 200) {
        // Parse the JSON response safely using Jackson
        JsonNode jsonResponse = objectMapper.readTree(response.body());
        // Extract the transcribed text from the "text" field
        return jsonResponse.get("text").asText();
    } else {
        // Handle API errors by throwing an exception with error details
        throw new RuntimeException("API request failed: " + response.body());
    }
}

Java

import io.github.cdimascio.dotenv.Dotenv;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;

public class CustomTranscription {
    
    // Instance variables to hold configuration and HTTP client
    private final String apiKey;
    private final String baseUrl;
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    
    public CustomTranscription() {
        // Load configuration from environment variables
        Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
        this.apiKey = dotenv.get("OPENAI_API_KEY");
        this.baseUrl = dotenv.get("OPENAI_BASE_URL");
        // Initialize HTTP client for making API requests
        this.httpClient = HttpClient.newHttpClient();
        // Initialize JSON parser for handling responses
        this.objectMapper = new ObjectMapper();
    }
    
    public String transcribeWithOptions(File audioFile, String language, String prompt) throws Exception {
        // Generate unique boundary for this multipart request
        String boundary = "----boundary" + System.currentTimeMillis();
        // Build the complete multipart form data
        byte[] formData = buildFormData(audioFile, boundary, language, prompt);
        
        // Create HTTP POST request with all necessary headers
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/v1/audio/transcriptions"))
            .header("Authorization", "Bearer " + apiKey) // API authentication
            .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Content type
            .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Request body
            .build();
            
        // Send request and get response
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        // Process the response
        if (response.statusCode() == 200) {
            // Parse JSON response safely using Jackson
            JsonNode jsonResponse = objectMapper.readTree(response.body());
            // Extract and return the transcribed text
            return jsonResponse.get("text").asText();
        } else {
            // Handle API errors with detailed error message
            throw new RuntimeException("API request failed: " + response.body());
        }
    }
    
    private byte[] buildFormData(File audioFile, String boundary, String language, String prompt) throws IOException {
        // Use StringBuilder to construct multipart form data
        StringBuilder formData = new StringBuilder();
        
        // Add model field - tells API which transcription model to use
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"model\"\r\n\r\n");
        formData.append("gpt-4o-mini-transcribe\r\n");
        
        // Add language field only if specified - helps with language detection
        if (language != null && !language.isEmpty()) {
            formData.append("--").append(boundary).append("\r\n");
            formData.append("Content-Disposition: form-data; name=\"language\"\r\n\r\n");
            formData.append(language).append("\r\n");
        }
        
        // Add prompt field only if specified - provides context for better accuracy
        if (prompt != null && !prompt.isEmpty()) {
            formData.append("--").append(boundary).append("\r\n");
            formData.append("Content-Disposition: form-data; name=\"prompt\"\r\n\r\n");
            formData.append(prompt).append("\r\n");
        }
        
        // Add file field with proper headers for the audio file
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(audioFile.getName()).append("\"\r\n");
        formData.append("Content-Type: audio/wav\r\n\r\n");
        
        // Convert text parts to bytes
        byte[] formBytes = formData.toString().getBytes();
        // Read the audio file content
        byte[] fileBytes = Files.readAllBytes(audioFile.toPath());
        // Create the closing boundary
        byte[] endBytes = ("\r\n--" + boundary + "--\r\n").getBytes();
        
        // Combine all parts into a single byte array
        byte[] result = new byte[formBytes.length + fileBytes.length + endBytes.length];
        // Copy form data headers
        System.arraycopy(formBytes, 0, result, 0, formBytes.length);
        // Copy audio file content
        System.arraycopy(fileBytes, 0, result, formBytes.length, fileBytes.length);
        // Copy closing boundary
        System.arraycopy(endBytes, 0, result, formBytes.length + fileBytes.length, endBytes.length);
        
        return result;
    }
    
    public static void main(String[] args) {
        try {
            // Create transcription service instance
            CustomTranscription transcriber = new CustomTranscription();
            
            // Specify the audio file to transcribe
            File audioFile = new File("recording.wav");
            
            // Transcribe with custom language and prompt parameters
            String result = transcriber.transcribeWithOptions(
                audioFile, 
                "en",  // Language: English
                "This is a meeting about project planning." // Context prompt
            );
            
            // Display the transcribed text
            System.out.println("Text: " + result);
            
        } catch (Exception e) {
            // Handle any errors that occur during transcription
            System.err.println("Transcription failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

import io.github.cdimascio.dotenv.Dotenv;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;

public class CustomTranscription {
    
    // Instance variables to hold configuration and HTTP client
    private final String apiKey;
    private final String baseUrl;
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    
    public CustomTranscription() {
        // Load configuration from environment variables
        Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
        this.apiKey = dotenv.get("OPENAI_API_KEY");
        this.baseUrl = dotenv.get("OPENAI_BASE_URL");
        // Initialize HTTP client for making API requests
        this.httpClient = HttpClient.newHttpClient();
        // Initialize JSON parser for handling responses
        this.objectMapper = new ObjectMapper();
    }
    
    public String transcribeWithOptions(File audioFile, String language, String prompt) throws Exception {
        // Generate unique boundary for this multipart request
        String boundary = "----boundary" + System.currentTimeMillis();
        // Build the complete multipart form data
        byte[] formData = buildFormData(audioFile, boundary, language, prompt);
        
        // Create HTTP POST request with all necessary headers
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/v1/audio/transcriptions"))
            .header("Authorization", "Bearer " + apiKey) // API authentication
            .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Content type
            .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Request body
            .build();
            
        // Send request and get response
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        // Process the response
        if (response.statusCode() == 200) {
            // Parse JSON response safely using Jackson
            JsonNode jsonResponse = objectMapper.readTree(response.body());
            // Extract and return the transcribed text
            return jsonResponse.get("text").asText();
        } else {
            // Handle API errors with detailed error message
            throw new RuntimeException("API request failed: " + response.body());
        }
    }
    
    private byte[] buildFormData(File audioFile, String boundary, String language, String prompt) throws IOException {
        // Use StringBuilder to construct multipart form data
        StringBuilder formData = new StringBuilder();
        
        // Add model field - tells API which transcription model to use
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"model\"\r\n\r\n");
        formData.append("gpt-4o-mini-transcribe\r\n");
        
        // Add language field only if specified - helps with language detection
        if (language != null && !language.isEmpty()) {
            formData.append("--").append(boundary).append("\r\n");
            formData.append("Content-Disposition: form-data; name=\"language\"\r\n\r\n");
            formData.append(language).append("\r\n");
        }
        
        // Add prompt field only if specified - provides context for better accuracy
        if (prompt != null && !prompt.isEmpty()) {
            formData.append("--").append(boundary).append("\r\n");
            formData.append("Content-Disposition: form-data; name=\"prompt\"\r\n\r\n");
            formData.append(prompt).append("\r\n");
        }
        
        // Add file field with proper headers for the audio file
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(audioFile.getName()).append("\"\r\n");
        formData.append("Content-Type: audio/wav\r\n\r\n");
        
        // Convert text parts to bytes
        byte[] formBytes = formData.toString().getBytes();
        // Read the audio file content
        byte[] fileBytes = Files.readAllBytes(audioFile.toPath());
        // Create the closing boundary
        byte[] endBytes = ("\r\n--" + boundary + "--\r\n").getBytes();
        
        // Combine all parts into a single byte array
        byte[] result = new byte[formBytes.length + fileBytes.length + endBytes.length];
        // Copy form data headers
        System.arraycopy(formBytes, 0, result, 0, formBytes.length);
        // Copy audio file content
        System.arraycopy(fileBytes, 0, result, formBytes.length, fileBytes.length);
        // Copy closing boundary
        System.arraycopy(endBytes, 0, result, formBytes.length + fileBytes.length, endBytes.length);
        
        return result;
    }
    
    public static void main(String[] args) {
        try {
            // Create transcription service instance
            CustomTranscription transcriber = new CustomTranscription();
            
            // Specify the audio file to transcribe
            File audioFile = new File("recording.wav");
            
            // Transcribe with custom language and prompt parameters
            String result = transcriber.transcribeWithOptions(
                audioFile, 
                "en",  // Language: English
                "This is a meeting about project planning." // Context prompt
            );
            
            // Display the transcribed text
            System.out.println("Text: " + result);
            
        } catch (Exception e) {
            // Handle any errors that occur during transcription
            System.err.println("Transcription failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Text: Today we discussed the project timeline and assigned tasks to each team member.

Text: Today we discussed the project timeline and assigned tasks to each team member.

XML

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.2</version>
</dependency>
<dependency>
    <groupId>io.github.cdimascio</groupId>
    <artifactId>dotenv-java</artifactId>
    <version>3.0.0</version>
</dependency>

gradle

implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2'
implementation 'io.github.cdimascio:dotenv-java:3.0.0'

Java

// Environment variable loading
import io.github.cdimascio.dotenv.Dotenv;
// JSON parsing and handling
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
// File operations
import java.io.File;
import java.io.IOException;
// HTTP client functionality
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
// File reading operations
import java.nio.file.Files;

Java

// Load environment variables from .env file (ignores if file doesn't exist)
Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
// Get the OpenAI API key from environment variables
String apiKey = dotenv.get("OPENAI_API_KEY");
// Get the base URL for API requests (allows for custom endpoints)
String baseUrl = dotenv.get("OPENAI_BASE_URL");
// Create HTTP client for making API requests
HttpClient httpClient = HttpClient.newHttpClient();
// Create JSON parser for handling API responses
ObjectMapper objectMapper = new ObjectMapper();

Java

// Create a File object pointing to the audio file to transcribe
File audioFile = new File("recording.wav");

Java

private byte[] buildFormData(File audioFile, String boundary, String language, String prompt) throws IOException {
    // StringBuilder to construct the multipart form data structure
    StringBuilder formData = new StringBuilder();
    
    // Add model field - specifies which transcription model to use
    formData.append("--").append(boundary).append("\r\n");
    formData.append("Content-Disposition: form-data; name=\"model\"\r\n\r\n");
    formData.append("gpt-4o-mini-transcribe\r\n");
    
    // Add language field only if provided - helps model focus on specific language
    if (language != null && !language.isEmpty()) {
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"language\"\r\n\r\n");
        formData.append(language).append("\r\n");
    }
    
    // Add prompt field only if provided - gives context to improve transcription accuracy
    if (prompt != null && !prompt.isEmpty()) {
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"prompt\"\r\n\r\n");
        formData.append(prompt).append("\r\n");
    }
    
    // Add file field with proper headers for audio file upload
    formData.append("--").append(boundary).append("\r\n");
    formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(audioFile.getName()).append("\"\r\n");
    formData.append("Content-Type: audio/wav\r\n\r\n");
    
    // Convert form data structure to bytes
    byte[] formBytes = formData.toString().getBytes();
    // Read the actual audio file content as bytes
    byte[] fileBytes = Files.readAllBytes(audioFile.toPath());
    // Create the final boundary marker to end the multipart data
    byte[] endBytes = ("\r\n--" + boundary + "--\r\n").getBytes();
    
    // Combine all parts: form headers + file content + end boundary
    byte[] result = new byte[formBytes.length + fileBytes.length + endBytes.length];
    System.arraycopy(formBytes, 0, result, 0, formBytes.length);
    System.arraycopy(fileBytes, 0, result, formBytes.length, fileBytes.length);
    System.arraycopy(endBytes, 0, result, formBytes.length + fileBytes.length, endBytes.length);
    
    return result;
}

Java

public String transcribeWithOptions(File audioFile, String language, String prompt) throws Exception {
    // Generate unique boundary for this request using current timestamp
    String boundary = "----boundary" + System.currentTimeMillis();
    // Build the multipart form data with all parameters
    byte[] formData = buildFormData(audioFile, boundary, language, prompt);
    
    // Create HTTP POST request to the transcription API endpoint
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(baseUrl + "/v1/audio/transcriptions"))
        .header("Authorization", "Bearer " + apiKey) // Authenticate with API key
        .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Specify content type
        .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Send form data as request body
        .build();
        
    // Send the request and receive the response
    HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    
    // Check if the request was successful (HTTP 200)
    if (response.statusCode() == 200) {
        // Parse the JSON response safely using Jackson
        JsonNode jsonResponse = objectMapper.readTree(response.body());
        // Extract the transcribed text from the "text" field
        return jsonResponse.get("text").asText();
    } else {
        // Handle API errors by throwing an exception with error details
        throw new RuntimeException("API request failed: " + response.body());
    }
}

Java

import io.github.cdimascio.dotenv.Dotenv;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;

public class CustomTranscription {
    
    // Instance variables to hold configuration and HTTP client
    private final String apiKey;
    private final String baseUrl;
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    
    public CustomTranscription() {
        // Load configuration from environment variables
        Dotenv dotenv = Dotenv.configure().ignoreIfMissing().load();
        this.apiKey = dotenv.get("OPENAI_API_KEY");
        this.baseUrl = dotenv.get("OPENAI_BASE_URL");
        // Initialize HTTP client for making API requests
        this.httpClient = HttpClient.newHttpClient();
        // Initialize JSON parser for handling responses
        this.objectMapper = new ObjectMapper();
    }
    
    public String transcribeWithOptions(File audioFile, String language, String prompt) throws Exception {
        // Generate unique boundary for this multipart request
        String boundary = "----boundary" + System.currentTimeMillis();
        // Build the complete multipart form data
        byte[] formData = buildFormData(audioFile, boundary, language, prompt);
        
        // Create HTTP POST request with all necessary headers
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/v1/audio/transcriptions"))
            .header("Authorization", "Bearer " + apiKey) // API authentication
            .header("Content-Type", "multipart/form-data; boundary=" + boundary) // Content type
            .POST(HttpRequest.BodyPublishers.ofByteArray(formData)) // Request body
            .build();
            
        // Send request and get response
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        // Process the response
        if (response.statusCode() == 200) {
            // Parse JSON response safely using Jackson
            JsonNode jsonResponse = objectMapper.readTree(response.body());
            // Extract and return the transcribed text
            return jsonResponse.get("text").asText();
        } else {
            // Handle API errors with detailed error message
            throw new RuntimeException("API request failed: " + response.body());
        }
    }
    
    private byte[] buildFormData(File audioFile, String boundary, String language, String prompt) throws IOException {
        // Use StringBuilder to construct multipart form data
        StringBuilder formData = new StringBuilder();
        
        // Add model field - tells API which transcription model to use
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"model\"\r\n\r\n");
        formData.append("gpt-4o-mini-transcribe\r\n");
        
        // Add language field only if specified - helps with language detection
        if (language != null && !language.isEmpty()) {
            formData.append("--").append(boundary).append("\r\n");
            formData.append("Content-Disposition: form-data; name=\"language\"\r\n\r\n");
            formData.append(language).append("\r\n");
        }
        
        // Add prompt field only if specified - provides context for better accuracy
        if (prompt != null && !prompt.isEmpty()) {
            formData.append("--").append(boundary).append("\r\n");
            formData.append("Content-Disposition: form-data; name=\"prompt\"\r\n\r\n");
            formData.append(prompt).append("\r\n");
        }
        
        // Add file field with proper headers for the audio file
        formData.append("--").append(boundary).append("\r\n");
        formData.append("Content-Disposition: form-data; name=\"file\"; filename=\"").append(audioFile.getName()).append("\"\r\n");
        formData.append("Content-Type: audio/wav\r\n\r\n");
        
        // Convert text parts to bytes
        byte[] formBytes = formData.toString().getBytes();
        // Read the audio file content
        byte[] fileBytes = Files.readAllBytes(audioFile.toPath());
        // Create the closing boundary
        byte[] endBytes = ("\r\n--" + boundary + "--\r\n").getBytes();
        
        // Combine all parts into a single byte array
        byte[] result = new byte[formBytes.length + fileBytes.length + endBytes.length];
        // Copy form data headers
        System.arraycopy(formBytes, 0, result, 0, formBytes.length);
        // Copy audio file content
        System.arraycopy(fileBytes, 0, result, formBytes.length, fileBytes.length);
        // Copy closing boundary
        System.arraycopy(endBytes, 0, result, formBytes.length + fileBytes.length, endBytes.length);
        
        return result;
    }
    
    public static void main(String[] args) {
        try {
            // Create transcription service instance
            CustomTranscription transcriber = new CustomTranscription();
            
            // Specify the audio file to transcribe
            File audioFile = new File("recording.wav");
            
            // Transcribe with custom language and prompt parameters
            String result = transcriber.transcribeWithOptions(
                audioFile, 
                "en",  // Language: English
                "This is a meeting about project planning." // Context prompt
            );
            
            // Display the transcribed text
            System.out.println("Text: " + result);
            
        } catch (Exception e) {
            // Handle any errors that occur during transcription
            System.err.println("Transcription failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Text: Today we discussed the project timeline and assigned tasks to each team member.

Introduction: Why Customize Transcription?

Recall: Basic Transcription with HTTP Requests

Join the 1M+ learners on CodeSignal

Key Custom Parameters: Language and Prompt

Building HTTP Requests with Custom Parameters

1. Setting Up the Dependencies and Imports

2. Setting Up the HTTP Client and Configuration

3. Preparing the Audio File

4. Building Multipart Form Data with Custom Parameters

5. Sending the Request and Parsing the Response

Full Example

Summary and Practice Preview