API reference
The Converter API turns spatial audio masters into IAMF and Eclipsa files from your own pipeline: create a conversion, upload the master, follow it to ready, download the IAMF. This reference is generated from the API's own OpenAPI document and lists every operation, object and error.
Base URL and format
| Environment | Base URL | Keys |
|---|---|---|
| Production | https://api.esfera.audio | live keys (esf_sk_live_…). |
| Staging | https://staging-api.esfera.audio | test keys (esf_sk_test_…), for design partners by arrangement. |
Every path starts with /v1. Requests and responses are JSON (application/json), except the master you upload, which goes straight to storage, and the IAMF you download, which is audio/iamf. Timestamps are ISO 8601 in UTC. Ids are UUIDs and are scoped to your account: another account's id is a not-found.
Resources
| Resource | What it covers |
|---|---|
| Conversions | Create a conversion, upload the master, follow it to ready, download the IAMF. |
| Webhooks | Register endpoints for conversion events; read and replay the delivery log. |
| Presets | What this deployment's encoder accepts: profiles and presets. |
| Usage | Minutes, period and limits for the key's account. |
| OpenAPI document | This document. |
Pagination
List endpoints take page (from 1, default 1) and pageSize (1 to 100, default 25) and return total, page and pageSize beside the rows. Conversions return them as items; webhook deliveries return them as deliveries.
Errors
Every error is an RFC 9457 problem document with a stable type URL. Match on type, never on title. The full list is on Errors.
Versioning
/v1 is a contract. The moment you integrate, this shape stays stable: breaking changes ship as /v2, which runs beside /v1. New optional fields and new problem types can appear in /v1, so ignore fields you do not recognise and treat an unknown problem type as its status code.
The OpenAPI document
This reference is generated from the OpenAPI 3.1 document the API itself serves at GET /v1/openapi.json. The document needs no key and is cacheable for five minutes. Use it to generate a client in a language the SDK does not cover.
Limits at a glance
| Limit | Value |
|---|---|
| Source duration | 180 minutes per file |
| Source size | 100 GiB per file (107,374,182,400 bytes) |
| Output retention | 72 hours after the conversion is ready |
| Request rate | 120 requests per minute per key. See Rate limits |
| Concurrent conversions | Per account, listed as limits.concurrent in Usage |