Pinch SDK Quickstart

This quickstart covers two common usage patterns:

a. Async / file-based translation

b. Streaming / real-time translation

Prerequisites

Account & access

To use the Pinch SDK, you’ll need:

• Login to Pinch
• Get a valid API key

You can create and manage API keys from the Pinch Developer Portal >

New accounts include free credits to get started.

Authentication

The Pinch SDK authenticates using the PINCH_API_KEY environment variable.

You can set this variable in one of two ways:

Option 1: Set it directly in your environment

export PINCH_API_KEY="pk_your_key_here"

$env:PINCH_API_KEY="pk_your_key_here"

Option 2: Use a .env file

Create a .env file in your project directory:

PINCH_API_KEY=pk_your_key_here

Keep your API key private. Do not commit it to GitHub or include it in client-side code.

Install the SDK

Using pip

python3 -m pip install pinch-sdk

python -m pip install pinch-sdk

Optional: audio helpers for resampling

If your input WAV files are not 16kHz or 48kHz, install audio helpers:

python3 -m pip install "pinch-sdk[audio]"

python -m pip install "pinch-sdk[audio]"

Using uv

uv add pinch-sdk

Run the script (example scripts given below)

Run the script from your project directory:

python3 translate.py

python translate.py

Example scripts

(a) Async / File-Based Translation

This approach is ideal when:

• you already have an audio file
• you want simple, one-shot translation

In this approach, you’ll run a Python script that:

• takes a WAV audio file as input
• generates a translated WAV audio file
• writes a transcript of the translated text

Create a small script in your project (for example, translate.py):

import asyncio
from pinch import PinchClient

async def main() -> None:
    client = PinchClient()  # reads PINCH_API_KEY

    await client.translate_file(
        input_wav_path="input.wav",
        output_wav_path="output.wav",
        transcript_path="transcript.txt",
        source_language="en-US",  # default
        target_language="es-ES",  # default
        audio_output_enabled=True # default
    )

if __name__ == "__main__":
    asyncio.run(main())

Outputs

After the script completes, you’ll see:

• output.wav - translated speech audio
• transcript.txt - translated text transcript

Example transcript output

(b) Streaming / Real-Time Translation

Streaming sessions are designed for low-latency, real-time use cases.

In this approach:

• audio is streamed in real-time
• transcripts + translated audio is returned in real-time

This example intentionally leaves playback or storage to the user’s preference.

Create a streaming session:

from pinch import PinchClient
from pinch.session import SessionParams

client = PinchClient()

session = client.create_session(
    SessionParams(
        source_language="en-US",
        target_language="es-ES",
    )
)

This session represents a live translation context.

Connect a streaming transport:

stream = await client.connect_stream(
    session,
    audio_output_enabled=True,
)

Once connected:

• the stream accepts incoming audio
• transcripts and translated audio are emitted as events

Stream audio into Pinch:

Audio is sent as raw PCM16 frames (for example, 20 ms chunks).

await stream.send_pcm16(
    pcm_bytes,
    sample_rate=16000,
    channels=1,
)

You can send audio from:

• a microphone
• a WAV file
• another real-time source

Pinch processes audio incrementally as it arrives.

Receive streaming outputs:

Pinch returns results as asynchronous events.

async for event in stream.events():
    if event.type == "transcript":
        # Partial or final transcript text
        print(event.text)

    elif event.type == "audio":
        # Translated speech as raw PCM16 bytes
        pcm_bytes = event.pcm16_bytes
        sample_rate = event.sample_rate

# Forward, buffer, save, or play this audio as needed

Audio is returned as data, not played automatically. Applications decide how to handle playback or storage.

Close the stream:

await stream.aclose()

Closing the stream signals that no more audio will be sent.

Input audio requirements

• Input must be 16-bit PCM WAV
• Supported sample rates:
  • 16,000 Hz (recommended)
  • 48,000 Hz
• Other sample rates require resampling helpers:

python3 -m pip install "pinch-sdk[audio]"

python -m pip install "pinch-sdk[audio]"

Language configuration

By default, the SDK uses:

• source_language = "en-US"
• target_language = "es-ES"

You can override these values when calling translate_file.

Pinch uses language codes (for example en-US, es-ES) rather than language names.

See Supported languages > for valid input and output codes.

SDK repository & examples

The Pinch Python SDK is open source and available on GitHub.

The repository includes:

• the full SDK source code
• sample example flies
• instructions for running the example using pip or uv

For implementation details and up-to-date examples, refer to the repository:

• GitHub >

Troubleshooting

The script exits immediately or raises an auth error

Common causes

• PINCH_API_KEY is missing or invalid
• credits are not enabled on your account
• network connectivity issues

What to check

• Confirm the PINCH_API_KEY environment variable is set:

  macOS Windows

  echo $PINCH_API_KEY

• Verify the key is active in the Pinch Portal

• Ensure your account has available credits

More ways to troubleshoot >