Documentation

Everything you need to ship

A quickstart that gets audio out of the API in two calls, the codes every endpoint speaks, the errors worth handling, and the governance terms — which are on this page rather than in a policy document because they change what your integration is allowed to do.

Quickstart

Translate a phrase and speak it, in two calls. Everything else in the API is a variation on this shape.

import { Pison } from "@pison/sdk"; const pison = new Pison({ apiKey: process.env.PISON_API_KEY }); // 1 — translateconst { output } = await pison.translate({  text: "Welcome to our community",  source: "en",  target: "yo",}); // 2 — speak itconst audio = await pison.speech.synthesize({  text: output,  voice: "yor-lagos-adunni",}); await audio.writeTo("welcome.mp3");

Set PISON_API_KEY in your environment. Everything the playground does, the API does.

Reference

Endpoints, and what each one is metered on

POST/v1/translateper 1M characters
Translate between English and any supported African language, with tone and diacritics preserved rather than normalised away.
POST/v1/speech/transcribeper hour of audio
Transcribe audio with a channel hint. Telephony-channel models are trained on 8 kHz narrowband rather than evaluated on it after the fact.
POST/v1/speech/synthesizeper 1M characters
Generate speech from a licensed voice. Tone marks are an input to the model, not something the text front-end strips before it gets there.
GET/v1/voicesfree
List and filter voices. Every voice carries its consent scope, so a client can refuse to synthesize outside what the speaker granted.
POST/v1/detectper 1k requests
Identify language and dialect from text or audio, with code-switching reported rather than collapsed into a single label.
POST/v1/culturalper 1k requests
Register, honorifics and address forms for a given language and context. Returns structured fields, and marks generated claims as generated.
POST/v1/embeddingsper 1M tokens
Multilingual embeddings trained on African-language text, so a Yoruba query and its English equivalent land near each other.
POST/v1/moderationper 1k requests
Safety classification that works in Pidgin and Hausa rather than only in English — the gap that lets abuse through an English-only filter.

Full request and response shapes, with runnable snippets, are on the developers page.

Errors

The ones worth handling, and what they actually mean

Two of these are specific to this API and are the ones to write code for: a voice can exist and still refuse a use its speaker did not grant, and a language can be covered for one capability and not another.

400
Malformed request
The body names what was wrong and which field.
401
Missing or invalid key
Keys are scoped per project and per endpoint.
403 consent_scope
Voice not cleared for this use
The voice exists; its speaker did not grant this purpose. The body lists the scopes that were granted.
404 language_unsupported
Language not covered for this endpoint
Coverage varies per capability. The body names which capabilities do cover it.
413
Payload too large
Audio over 100MB or text over the per-tier character ceiling.
429
Rate limited
Concurrency, not requests per second. Retry-After is always set.
503 model_warming
Cold start on a low-traffic language
Retry once after the interval given. Only happens on languages outside the first five.

Governance

Data governance

Seven commitments, written to be audited against

These are on the documentation rather than in a policy PDF because they change what your integration is permitted to do. Pison Labs is registered at NDPA Ultra-High Level (NDPC UHL-2026-0417) with a designated data protection officer and annual compliance audit returns.

Enumerated consent: Every speaker consents separately to research, commercial use, TTS synthesis, voice cloning, third-party licensing and model training. No bundled grants and no blanket future-media language. Consent is administered in the speaker's own language and the text version is recorded with it.
Revocable, with propagation: Withdrawal is honoured within 30 days and removes the speaker from every future dataset version. We disclose the honest limit alongside it: a model already trained cannot be made to unlearn a voice.
Published compensation: Rates per validated recording, per review and per translated sentence are public, as is the marketplace revenue share and the acceptance rate.
Community benefit for community knowledge: Proverbs, folklore and oral histories are collected under community-level agreement with a named benefit-sharing arrangement and released openly rather than licensed.
Provenance on every record: Source, rights holder, licence, chain of title, retrieval date and verification status — structured for publication from the first record rather than reconstructed later.
Grant-funded corpora stay separate: Data collected under an open, grant-funded consent is never relicensed commercially. The two stacks are physically and legally separate.
Children's data: Only with verified guardian consent, only where scientifically necessary, and never for voice cloning. It is genuinely needed for education speech recognition and it is the highest-risk category in every jurisdiction involved.

Status

Service status

Translation APIOperational
Speech to textOperational
Text to speechOperational
Voice libraryOperational
Language detectionOperational
Cultural intelligenceOperational
DubbingBeta
Voice agentsBeta

Beta services carry no SLA. Incidents and maintenance windows are announced here and by email to every project owner.

Get an API key

Self-serve to the Business tier. Sales enters where private deployment and a contractual SLA do, and not before.

See pricing Try it in the browser

Everything you need to ship

Quickstart

Translate a phrase and speak it, in two calls. Everything else in the API is a variation on this shape.

import { Pison } from "@pison/sdk"; const pison = new Pison({ apiKey: process.env.PISON_API_KEY }); // 1 — translateconst { output } = await pison.translate({  text: "Welcome to our community",  source: "en",  target: "yo",}); // 2 — speak itconst audio = await pison.speech.synthesize({  text: output,  voice: "yor-lagos-adunni",}); await audio.writeTo("welcome.mp3");

Set PISON_API_KEY in your environment. Everything the playground does, the API does.

Endpoints, and what each one is metered on

POST/v1/translateper 1M characters
Translate between English and any supported African language, with tone and diacritics preserved rather than normalised away.
POST/v1/speech/transcribeper hour of audio
Transcribe audio with a channel hint. Telephony-channel models are trained on 8 kHz narrowband rather than evaluated on it after the fact.
POST/v1/speech/synthesizeper 1M characters
Generate speech from a licensed voice. Tone marks are an input to the model, not something the text front-end strips before it gets there.
GET/v1/voicesfree
List and filter voices. Every voice carries its consent scope, so a client can refuse to synthesize outside what the speaker granted.
POST/v1/detectper 1k requests
Identify language and dialect from text or audio, with code-switching reported rather than collapsed into a single label.
POST/v1/culturalper 1k requests
Register, honorifics and address forms for a given language and context. Returns structured fields, and marks generated claims as generated.
POST/v1/embeddingsper 1M tokens
Multilingual embeddings trained on African-language text, so a Yoruba query and its English equivalent land near each other.
POST/v1/moderationper 1k requests
Safety classification that works in Pidgin and Hausa rather than only in English — the gap that lets abuse through an English-only filter.

Full request and response shapes, with runnable snippets, are on the developers page.

The ones worth handling, and what they actually mean

400
Malformed request
The body names what was wrong and which field.
401
Missing or invalid key
Keys are scoped per project and per endpoint.
403 consent_scope
Voice not cleared for this use
The voice exists; its speaker did not grant this purpose. The body lists the scopes that were granted.
404 language_unsupported
Language not covered for this endpoint
Coverage varies per capability. The body names which capabilities do cover it.
413
Payload too large
Audio over 100MB or text over the per-tier character ceiling.
429
Rate limited
Concurrency, not requests per second. Retry-After is always set.
503 model_warming
Cold start on a low-traffic language
Retry once after the interval given. Only happens on languages outside the first five.

Seven commitments, written to be audited against

Enumerated consent

Every speaker consents separately to research, commercial use, TTS synthesis, voice cloning, third-party licensing and model training. No bundled grants and no blanket future-media language. Consent is administered in the speaker's own language and the text version is recorded with it.

Revocable, with propagation

Withdrawal is honoured within 30 days and removes the speaker from every future dataset version. We disclose the honest limit alongside it: a model already trained cannot be made to unlearn a voice.

Published compensation

Rates per validated recording, per review and per translated sentence are public, as is the marketplace revenue share and the acceptance rate.

Community benefit for community knowledge

Proverbs, folklore and oral histories are collected under community-level agreement with a named benefit-sharing arrangement and released openly rather than licensed.

Provenance on every record

Source, rights holder, licence, chain of title, retrieval date and verification status — structured for publication from the first record rather than reconstructed later.

Grant-funded corpora stay separate

Data collected under an open, grant-funded consent is never relicensed commercially. The two stacks are physically and legally separate.

Children's data

Only with verified guardian consent, only where scientifically necessary, and never for voice cloning. It is genuinely needed for education speech recognition and it is the highest-risk category in every jurisdiction involved.

Service status

Translation APIOperational
Speech to textOperational
Text to speechOperational
Voice libraryOperational
Language detectionOperational
Cultural intelligenceOperational
DubbingBeta
Voice agentsBeta

Beta services carry no SLA. Incidents and maintenance windows are announced here and by email to every project owner.