Endpoint Reference
All endpoints share the base path: https://api.soundtitle.org/v1 (planned). Slugs below are relative paths.
Authorization tiers: Transmission = no additional auth needed (call = consent); Public = always open; Creation = separate authorization required; Restricted = request → approval → time-limited token.
1. Call Regeneration (Transmission Tier)
Real-time voice regeneration during calls — the owner is actively speaking, the registry relays. No additional authorization needed.
| Endpoint (slug) | Method | Input | Output | Auth Tier | Billing |
|---|---|---|---|---|---|
transmit-realtime |
POST | profile_id, audio_stream, codebook_version |
audio_stream (regenerated) |
Transmission | Per call-minute |
transmit-session-status |
GET | session_id |
{ status, duration, bytes_transmitted } |
Transmission | Free |
2. Verification (Public)
Check whether a voice has been authorized for a given purpose. Always public, metered per call.
| Endpoint (slug) | Method | Input | Output | Auth Tier | Billing |
|---|---|---|---|---|---|
verify |
POST | profile_id, audio_sample, purpose |
{ status, receipt_id, timestamp } |
Public | Per call |
verify-batch |
POST | [{ profile_id, audio_hash, purpose }] |
[{ profile_id, status, receipt_id }] |
Public | Batch discount |
3. Generate API (Creation Tier)
Generate speech the owner has never spoken. Requires separate authorization, dual-metered by character + duration, with mandatory ingredient sheet. Synthetic output must be labeled: "Synthetic creation, not sung or spoken by the person in life."
| Endpoint (slug) | Method | Input | Output | Auth Tier | Billing |
|---|---|---|---|---|---|
generate |
POST | profile_id, text, style_ref, purpose |
{ audio_url, ingredient_sheet, receipt_id } |
Creation | Per character + duration |
generate-status |
GET | task_id |
{ status, progress, estimated_completion } |
Creation | Free |
generate-history |
GET | profile_id, date_range |
[{ task_id, text, created_at, ingredient_sheet }] |
Creation (owner only) | Free |
4. Marketplace (Public-Tier Sample Library)
Public voice sample library — free search, paid call, voice owner revenue share.
| Endpoint (slug) | Method | Input | Output | Auth Tier | Billing |
|---|---|---|---|---|---|
marketplace-search |
GET | query, language, gender, age_range, style_tags |
[{ profile_id, public_label, sample_preview_url, price_per_use }] |
Public tier | Free search; use is paid |
marketplace-purchase |
POST | profile_id, purpose, usage_scope |
{ license_id, audio_url, ingredient_sheet, receipt_id } |
Public + usage agreement | Per use; owner royalty |
marketplace-split-report |
GET | profile_id, date_range |
{ total_earnings, transactions } |
Restricted (owner only) | Free |
5. Ledger Access
Owner views full receipt chain; restricted tier queries require request → approval → time-limited token flow.
| Endpoint (slug) | Method | Input | Output | Auth Tier | Billing |
|---|---|---|---|---|---|
ledger-query |
GET | profile_id, event_type, date_range |
{ receipts, chain_valid } |
Owner full; restricted needs token | Free for owner; per call for others |
ledger-access-request |
POST | profile_id, requester_id, purpose, field_scope |
{ request_id, status: "PENDING" } |
Restricted | Free to submit |
ledger-access-approve |
POST | request_id, token_ttl_seconds |
{ access_token, expires_at, allowed_fields } |
Restricted (approval required) | Free |
🚧 Metering & Billing Details (Coming Soon)
Detailed metering rules, unit pricing, free tier allowances, invoicing, and settlement cycles will be published when backend implementation begins.