# Pinch API

> Speech translation API. Real-time audio translation and async video dubbing.

Base URL: https://api.startpinch.com
Auth: Bearer token in Authorization header
API keys: https://portal.startpinch.com/dashboard/developers

## Products

### Real-time Translation
Stream audio in, get translated audio and transcripts back in real time. 50+ languages with voice cloning.
- Python SDK: `pip install pinch-sdk`
- WebSocket via LiveKit client
- Docs: https://www.startpinch.com/docs/sdk-quickstart
- Node.js demo: https://github.com/pinch-eng/pinch-realtime-demo

### Video Dubbing
Submit a video URL, get a fully dubbed version. Async REST API.
- $0.50/min, max 60 min, max 2 GB
- Languages: en, es, fr, de, it, pt, ru, ja, ko, zh
- Docs: https://www.startpinch.com/docs/dubbing-quickstart

### MCP Connector
Remote MCP server for dubbing, usable from Claude.ai, Claude Cowork, and Claude Code.
- MCP endpoint: https://portal.startpinch.com/api/mcp
- Auth: OAuth 2.1 (Sign in with Pinch); scopes: dubbing, apikeys:write
- Tools: dub_video, get_dub_status, get_dub_result, list_dubs, list_supported_languages, get_balance, create_dubbing_api_key, list_dubbing_api_keys, revoke_api_key
- Docs: https://www.startpinch.com/docs/mcp

## Real-time API

POST /api/beta1/session — Create translation session
Request: { "sourceLanguage": "en-US", "targetLanguage": "es-ES", "voiceType": "clone" }
Response: { "url": "wss://...", "token": "...", "room_name": "api-..." }
Connect to the returned WebSocket URL with a LiveKit client, publish microphone audio, receive translated audio tracks and transcript data messages.

## Dubbing API

POST /api/dubbing/upload-url — Get presigned upload URL (optional)
Request: { "filename": "video.mp4", "content_type": "video/mp4" }
Response: { "upload_url": "https://...", "source_url": "https://...", "upload_id": "...", "max_file_size_bytes": 500000000, "expires_in_sec": 3600 }

POST /api/dubbing/jobs — Create dubbing job
Request: { "source_url": "https://...", "target_lang": "es", "source_lang": "auto" }
Response: { "job_id": "...", "status": "pending", ... }

GET /api/dubbing/jobs/{id} — Poll job status
Response: { "job_id": "...", "status": "completed", "output_url": "https://...", ... }
Statuses: pending → downloading → processing → uploading → completed | failed

GET /api/dubbing/jobs/{id}/result — Get fresh download URL
Response: { "job_id": "...", "download_url": "https://...", "expires_at": "..." }

GET /api/dubbing/jobs?limit=20&offset=0 — List jobs

## Links

- Full docs: https://www.startpinch.com/docs
- Full API reference (machine-readable): https://www.startpinch.com/llms-full.txt
- OpenAPI spec: https://www.startpinch.com/openapi.json
- Python SDK: https://github.com/pinch-eng/pinch-python-sdk
- Node.js demo: https://github.com/pinch-eng/pinch-realtime-demo
- Developer portal: https://portal.startpinch.com/dashboard/developers