AI Voice Agent Models and Voices

Use the discovery endpoints to build selectors in your UI and to validate configuration before sending create or update requests. Both endpoints require the same bearer API key used for the rest of the public API.

Models Endpoint

Endpoint	Method	Auth
/v1/ai/models	GET	Required

curl -sS https://api.minivoice.eu/v1/ai/models \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "data": [
    {
      "id": "gpt-realtime-2",
      "type": "realtime",
      "default": true
    },
    {
      "id": "gpt-4.1-mini",
      "type": "turn_based"
    },
    {
      "id": "gpt-4.1",
      "type": "turn_based"
    },
    {
      "id": "gpt-4o-mini",
      "type": "turn_based"
    },
    {
      "id": "gpt-4o",
      "type": "turn_based"
    }
  ]
}

Agent creation defaults to gpt-4.1-mini when you omit model, even though the discovery response marks gpt-realtime-2 as the realtime default. Treat the create response as the source of truth for the model actually stored on the agent.

Voices Endpoint

Endpoint	Method	Auth
/v1/ai/voices	GET	Required

curl -sS https://api.minivoice.eu/v1/ai/voices \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "data": [
    {
      "id": "alloy",
      "name": "Alloy",
      "supported_runtimes": [
        "realtime",
        "turn_based"
      ]
    },
    {
      "id": "nova",
      "name": "Nova",
      "supported_runtimes": [
        "realtime",
        "turn_based"
      ]
    },
    {
      "id": "shimmer",
      "name": "Shimmer",
      "supported_runtimes": [
        "realtime",
        "turn_based"
      ]
    }
  ]
}

The full public voice allowlist is alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, and verse. Agent creation defaults to alloy.

Common Use Case

A customer settings page should load models and voices when the page opens, then use those lists to populate dropdowns. Store only the selected id in your create or update request.

{
  "name": "Appointment Scheduler",
  "model": "gpt-4.1-mini",
  "voice": "shimmer",
  "greeting": "Thanks for calling. Are you trying to book, reschedule, or cancel an appointment?",
  "instructions": "Help callers with appointment scheduling. Ask for date, time, and preferred provider."
}

Common Failure

{
  "error": {
    "code": "invalid_voice",
    "message": "voice is not supported",
    "allowed_values": [
      "alloy",
      "ash",
      "ballad",
      "coral",
      "echo",
      "fable",
      "nova",
      "onyx",
      "sage",
      "shimmer",
      "verse"
    ]
  }
}

Testing

Fetch both discovery endpoints in your test environment and assert that your UI can render an option for every returned item. Then create one agent using a non-default valid voice, read the agent back, and confirm the stored voice matches the request.