Skip to main content
Modulate exposes two API surfaces with different authentication schemes. The Models API covers every model endpoint documented on this site. The Modulate Platform API is a separate early-access orchestration surface, covered at the end of this page.

​
API keys

Generate keys from the API Keys page in the dashboard. A key belongs to an organization. Model access and usage limits are properties of the organization, not of the individual key, and they are fixed once the key is issued.
API key creation screen

​
Passing the key

HTTP endpoints take the key as a request header:
WebSocket endpoints take it as a query parameter on the connection URL. A header cannot be used, because the key must be present during the handshake:
This applies to every Models API endpoint. HTTP endpoints are the /api/velma-2-*-batch paths plus /api/velma-2-batch; WebSocket endpoints are the /api/velma-2-*-streaming paths plus /api/velma-2-streaming.
API keys in WebSocket URLs can appear in server access logs and proxy logs. Avoid logging or persisting the full connection URL.

​
Limits

Concurrency is capped per model: the number of requests or connections in flight at the same time against one endpoint. The default is 3. Reaching it on one model does not affect any other model. Credits are separate. A request is rejected for insufficient credits whatever the concurrency situation. Concurrency ceilings are set by Modulate per organization. To raise one, contact us with the model and the traffic you expect.

​
Error responses

​
Authentication

A 403 has two causes. Read the detail field to tell them apart. The per-endpoint reference page lists the exact set each endpoint returns. On WebSocket endpoints the handshake closes instead of returning a status: An error message carrying the reason is sent before each close.

​
Limits

Every rejected-for-limits request returns 429. The detail field names the cause: On WebSocket endpoints these arrive as close codes 4030, 4029, and 4031. Emotion Detection and Accent Detection (batch) declare 429 for insufficient credits only. Match on the detail string rather than on 429 alone. For a backlog of files, bound the work with a semaphore rather than retrying into a full queue:

​
Modulate Platform API

The Modulate Platform API (cloud-processing-api.modulate.ai) submits jobs that combine transcription with optional analysis features such as emotion, demographics, deepfake detection, and behavioral insights. It authenticates differently from the Models API.
The Platform API is in early access. Any part of the contract can change before 1.0.0.
Every request carries two headers:
accountuuid comes from an account administrator or the Platform dashboard. apikey is a Platform key, issued separately from Models API keys. A single POST /api_service endpoint accepts three submission patterns:
  • Real-time WebSocket: submission_type: "realtime_websocket" with no files. The response carries a realtime_url for streaming through the Pipecat Client SDK.
  • Single-file batch: one audio file of 5 MB or less in a single POST.
  • Multi-file batch: one POST per file sharing a job_id, with finalize_job: true on the last.
All three then poll GET /api_service/job_status/{job_id} until status='completed'.