Choosing a voice, model, and transcriber

Before an assistant can take a call it needs three IDs: a voice to speak with, a language model to reason with, and a transcriber to hear with. All three come from read-only catalogues that OnCore maintains for you: browse a catalogue, pick a row, keep its id.

For the endpoint-by-endpoint schemas, see the Voices, Models & Transcribers reference.

How the catalogues work#

The three catalogues behave identically, so learning one teaches you all three:

• They are read-only. Only GET is exposed; you choose from what OnCore offers rather than registering your own entries.
• Every list is paginated and reports a total, so you can tell when you have seen everything.
• Every response uses the standard envelope: the payload sits in data, alongside success and metadata. See Conventions.
• Store the id, never the display name. name is a label that can repeat (the same voice can appear more than once under different underlying models), while id is the stable reference. Versioning explains why these catalogues are expected to grow.

All three list endpoints take the same two query parameters:

Pick a voice#

GET /voices returns the catalogue; GET /voices/{id} returns a single entry once you know its ID.

curl "https://core-api.heysadie.ai/voices?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

The list arrives in data.voices, with the catalogue size in data.total:

{
  "success": true,
  "data": {
    "voices": [
      {
        "id": "0195f1e2-5555-7000-8000-000000000000",
        "name": "Example Voice",
        "provider": "example-provider"
      }
    ],
    "total": 42
  },
  "metadata": {
    "timestamp": "2026-07-30T12:00:00.000Z",
    "version": "1.0",
    "path": "/voices"
  }
}

Each entry in data.voices carries these fields:

GET /voices/{id} returns the same fields, but as a bare object in data rather than inside a voices array:

curl https://core-api.heysadie.ai/voices/0195f1e2-5555-7000-8000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY"

{
  "id": "0195f1e2-5555-7000-8000-000000000000",
  "name": "Example Voice",
  "provider": "example-provider"
}

If your callers do not all speak the same language, read Multi-language calls before you settle on a voice. Some voices in the catalogue speak one language and others speak several, and that choice decides who your assistant can serve.

Pick a language model#

GET /models lists the language models an assistant can reason with; GET /models/{id} returns one of them.

curl "https://core-api.heysadie.ai/models?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

The list arrives in data.models, with the catalogue size in data.total:

{
  "models": [
    {
      "id": "0195f1e2-6666-7000-8000-000000000000",
      "name": "Example Model",
      "model": "example-model-v1",
      "provider": "example-provider"
    }
  ],
  "total": 12
}

GET /models/{id} returns the same fields as a bare object in data:

curl https://core-api.heysadie.ai/models/0195f1e2-6666-7000-8000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY"

Pick a transcriber#

The transcriber is the speech-to-text engine that turns what the caller says into text for the model. GET /transcribers lists the catalogue; GET /transcribers/{id} returns one entry.

curl "https://core-api.heysadie.ai/transcribers?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

The list arrives in data.transcribers, with the catalogue size in data.total:

{
  "transcribers": [
    {
      "id": "0195f1e2-7777-7000-8000-000000000000",
      "name": "Example Transcriber",
      "provider": "example-provider"
    }
  ],
  "total": 8
}

A transcriber entry has no language field, so this page does not state which languages any given transcriber covers.

curl https://core-api.heysadie.ai/transcribers/0195f1e2-7777-7000-8000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY"

Use the three IDs#

Once you have one id from each catalogue, pass them to the assistant as voiceId, modelId, and transcriberId: on POST /assistants when you create it, or on PATCH /assistants/{id} to swap one later.

curl -X PATCH https://core-api.heysadie.ai/assistants/0195f1e2-2222-7000-8000-000000000000 \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceId": "0195f1e2-5555-7000-8000-000000000000",
    "modelId": "0195f1e2-6666-7000-8000-000000000000",
    "transcriberId": "0195f1e2-7777-7000-8000-000000000000"
  }'

Because the catalogues grow, resolve these IDs once and store them rather than looking them up on every call. Re-check them when you want a newly added voice or model. Assistants covers the rest of the configuration these three IDs sit alongside.

When a lookup fails#

All six endpoints return the standard error envelope, made up of success: false plus an error object with a machine-readable code, a human-readable message, and, for validation failures, a details array of { field, message } entries:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Voice not found"
  },
  "metadata": {
    "timestamp": "2026-07-30T12:00:00.000Z",
    "version": "1.0",
    "path": "/voices/0195f1e2-5555-7000-8000-000000000000"
  }
}

Each of the six can answer 400, 401, 403, 404, or 500. Branch on error.code, never on error.message. Errors lists every code and what it means.

Noisy callers#

Every call runs background noise reduction on the caller's audio before it reaches the transcriber. It is always on and there is nothing to configure: a caller in a car, a cafe or a warehouse is already handled, and you do not need to pick a transcriber for robustness to noise.

What it does not remove is a second person talking nearby, which the transcriber may still pick up as caller speech. If an assistant reacts to something the caller did not say, that is usually the cause rather than the transcriber choice.

Next steps#

• Create and configure an assistant: put the three IDs to work and set the rest of the assistant up.
• Expressive mode: how the voice you picked decides whether the assistant can steer its own delivery.
• Voices, Models & Transcribers reference: the generated schema for all six endpoints, always current with the live API.