Java

import com.neosapience.TypecastClient;
import com.neosapience.models.*;

import java.io.FileOutputStream;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // Initialize client
        TypecastClient client = new TypecastClient("YOUR_API_KEY");

        // Convert text to speech
        TTSRequest request = TTSRequest.builder()
                .voiceId("tc_672c5f5ce59fac2a48faeaee")
                .text("Hello there! I'm your friendly text-to-speech agent.")
                .model(TTSModel.SSFM_V30)
                .build();

        TTSResponse response = client.textToSpeech(request);

        // Save audio file
        try (FileOutputStream fos = new FileOutputStream("output." + response.getFormat())) {
            fos.write(response.getAudioData());
        }

        System.out.println("Audio saved! Duration: " + response.getDuration() + "s, Format: " + response.getFormat());

        // Clean up
        client.close();
    }
}

// Using environment variable
// export TYPECAST_API_KEY="your-api-key-here"
TypecastClient client = new TypecastClient();

// Or pass directly
TypecastClient client = new TypecastClient("your-api-key-here");

// Or with custom base URL
TypecastClient client = new TypecastClient("your-api-key-here", "https://custom-api.example.com");

TYPECAST_API_KEY=your-api-key-here

TTSRequest request = TTSRequest.builder()
        .voiceId("tc_672c5f5ce59fac2a48faeaee")
        .text("Customized audio output!")
        .model(TTSModel.SSFM_V30)
        .output(Output.builder()
                .targetLufs(-14.0)                 // Range: -70 to 0 (LUFS)
                .audioPitch(2)                  // Range: -12 to +12 semitones
                .audioTempo(1.2)                // Range: 0.5x to 2.0x
                .audioFormat(AudioFormat.MP3)   // Options: WAV, MP3
                .build())
        .seed(42)  // For reproducible results
        .build();

TTSResponse response = client.textToSpeech(request);

try (FileOutputStream fos = new FileOutputStream("output." + response.getFormat())) {
    fos.write(response.getAudioData());
}
System.out.println("Duration: " + response.getDuration() + "s, Format: " + response.getFormat());

// Get all voices
List<VoiceV2Response> voices = client.getVoicesV2();

// Filter by criteria
VoicesV2Filter filter = VoicesV2Filter.builder()
        .model(TTSModel.SSFM_V30)
        .gender(GenderEnum.FEMALE)
        .age(AgeEnum.YOUNG_ADULT)
        .build();

List<VoiceV2Response> filtered = client.getVoicesV2(filter);

// Display voice info
for (VoiceV2Response voice : voices) {
    System.out.println("ID: " + voice.getVoiceId() + ", Name: " + voice.getVoiceName());
    System.out.println("Gender: " + voice.getGender() + ", Age: " + voice.getAge());
    
    for (ModelInfo model : voice.getModels()) {
        System.out.println("Model: " + model.getVersion() + ", Emotions: " + model.getEmotions());
    }
    
    if (voice.getUseCases() != null) {
        System.out.println("Use cases: " + String.join(", ", voice.getUseCases()));
    }
}

// Auto-detect language (recommended)
TTSRequest request = TTSRequest.builder()
        .voiceId("tc_672c5f5ce59fac2a48faeaee")
        .text("こんにちは。お元気ですか。")
        .model(TTSModel.SSFM_V30)
        .build();

TTSResponse response = client.textToSpeech(request);

// Or specify language explicitly
TTSRequest koreanRequest = TTSRequest.builder()
        .voiceId("tc_672c5f5ce59fac2a48faeaee")
        .text("안녕하세요. 반갑습니다.")
        .model(TTSModel.SSFM_V30)
        .language(LanguageCode.KOR)  // ISO 639-3 language code
        .build();

TTSResponse koreanResponse = client.textToSpeech(koreanRequest);

try (FileOutputStream fos = new FileOutputStream("output." + response.getFormat())) {
    fos.write(response.getAudioData());
}

import com.neosapience.TypecastClient;
import com.neosapience.exceptions.*;

try {
    TTSResponse response = client.textToSpeech(request);
} catch (UnauthorizedException e) {
    // 401: Invalid API key
    System.err.println("Invalid API key: " + e.getMessage());
} catch (PaymentRequiredException e) {
    // 402: Insufficient credits
    System.err.println("Insufficient credits: " + e.getMessage());
} catch (ForbiddenException e) {
    // 403: Access denied
    System.err.println("Access denied: " + e.getMessage());
} catch (NotFoundException e) {
    // 404: Resource not found
    System.err.println("Voice not found: " + e.getMessage());
} catch (UnprocessableEntityException e) {
    // 422: Validation error
    System.err.println("Validation error: " + e.getMessage());
} catch (RateLimitException e) {
    // 429: Rate limit exceeded
    System.err.println("Rate limit exceeded - please retry later");
} catch (InternalServerException e) {
    // 500: Server error
    System.err.println("Server error: " + e.getMessage());
} catch (TypecastException e) {
    // Generic error
    System.err.println("API error (" + e.getStatusCode() + "): " + e.getMessage());
}