Browse API documentation
Apply for API access

Data handling

Know where developer content goes and how long it remains.

Developer API content, credentials, cache records, and usage accounting are isolated from the consumer product. This page documents the v1 handling contract; customers with additional requirements should declare them in the access application.

Updated September 15, 2026 · API version 1

Content processing

Submitted text is sent only to the processing path required by the selected endpoint. Diacritization and Pinglish use the VowelMarks reading engine; translation and Premium speech use managed providers. Basic Kian and Leyla requests pass through VowelMarks to Microsoft Edge Read Aloud; Ava, Mana, and Amir run in VowelMarks' self-hosted Basic speech service. The public API uses stable VowelMarks voice names rather than upstream model identifiers.

  • VowelMarks does not use customer content for its own model training or human quality review without a separate explicit opt-in. Upstream processing is subject to the applicable provider terms; this page does not make an additional provider-training guarantee.
  • Validation and source-preservation checks run before a successful result is delivered.
  • Developer data is not placed in consumer quota tables or consumer content records.

Organization-isolated cache

Only successful requested-voice results are cached. Cache identity includes organization, environment, endpoint, the exact input and options, and the stable engine version, so one customer's content is never used to answer another customer's request. A one-time Kian/Leyla-to-Ava fallback is returned but is not stored as the selected voice.

  • Cached text and audio expire 30 days after last access.
  • Sliding-expiry metadata is refreshed at most once per day.
  • Owners and VowelMarks administrators can purge an organization's cached content.
  • Audio lives in the developer object store and is downloaded through a signed URL valid for one hour.
  • Errors are not cached.

Speech job retention

Production Basic jobs store the exact job request in private object storage so a durable worker can continue after the creation connection closes. They also store operational state, ordered event indexes, and temporary MP3 preview chunks. Premium jobs remain a development/staging preview and add temporary completed-section PCM checkpoints. The current buffered Premium experiment omits the store field, so Google's documented default provider retention still applies; the Workflow does not rely on stored-interaction recovery. VowelMarks waits for each complete provider response, validates it, and privately checkpoints the completed PCM section before continuing. The earlier foreground-stream recovery experiment explicitly used store: true so the Workflow could attempt same-interaction recovery, but that provider read or resume was not reliably available. Long-form Premium completion and restart recovery remain under validation and disabled in production.

  • VowelMarks job input, result metadata, and replayable event data expire after 24 hours.
  • Completed final audio follows the normal organization-isolated 30-day sliding cache policy.
  • Each signed final-audio URL expires after one hour; polling a succeeded job during its 24-hour lifetime issues a fresh URL.
  • Disconnecting from the event stream does not cancel or delete the job.
  • Google's current Interactions API retention documentation states that store defaults to true, with a one-day Free Tier default and a 55-day Paid Tier default; Paid Tier projects can configure 7, 14, 28, or 55 days. The applicable window depends on the provider project's tier and configuration. The current buffered Premium experiment omits the field, so this provider-default retention still applies even though the Workflow does not use stored-interaction recovery.
  • VowelMarks' 24-hour job purge and 30-day cache policy do not describe or shorten any upstream provider-retention window. Provider storage and deletion are administered under the provider terms and controls.

Logs and telemetry

Operational telemetry may include the request ID, organization and key public identifiers, endpoint, HTTP status, metered units, cache outcome, stable engine version, latency, and selected internal lane. It must not contain submitted text, generated text or audio, authorization values, raw URLs, invitation tokens, personal identifiers, prompts, or provider response bodies.

Allowed: request_id, endpoint, status, units, cache_hit, engine_version, latency
Excluded: text, output, audio, Authorization, invite token, raw URL, personal identity

Billing and account records

Organization, membership, application, terms-acceptance, entitlement, usage-ledger, idempotency, billing-event, and append-only administrator audit records are retained separately from cached customer content. Cache purge does not erase financial, security, or audit records needed to operate the account.

  • API keys are shown once; VowelMarks stores a keyed digest plus safe display metadata, not the reusable secret.
  • Idempotency results are retained for 24 hours.
  • Normal cancellation preserves portal and test access; live keys stop at the paid period end.
  • No public service-level agreement is offered in v1.