> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyager.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Discover the models your workspace can run with GET /v1/models, and read each model's input_schema and operations before you create a job.

The model list changes as Voyager adds models, so read it from the API instead of hard-coding it. `GET /v1/models` lists what you can run; `GET /v1/models/{id}` tells you exactly what `input` a model takes.

## List models

```bash theme={"system"}
curl "https://api.voyager.so/v1/models?type=video" \
  -H "Authorization: Bearer $VOYAGER_API_KEY"
```

| Parameter | Type | Description |
| - | - | - |
| `type` | `string` or `null` | Only models of this job type. One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. |
| `operation` | `string` or `null` | Only models that run this operation. |
| `q` | `string` or `null` | Words in the id, name or description. Up to 100 characters. |
| `limit` | `integer` | 1–100. Default `50`. |
| `cursor` | `string` or `null` | Up to 400 characters. |

The list includes models above your plan, marked `available: false`, so you can see what an upgrade adds. `available` is `null` when it isn't known yet; creating the job then decides.

The response below is an **illustrative example of the shape**, not a real or complete list:

```json theme={"system"}
{
  "object": "list",
  "data": [
    {
      "id": "example-video-model",
      "object": "model",
      "name": "Example Video Model",
      "type": "video",
      "summary": "Short cinematic clips from text or an image.",
      "best_for": "Product shots and image-to-video",
      "default": false,
      "status": "active",
      "operations": ["text-to-video", "image-to-video"],
      "available": true,
      "unavailable_reason": null,
      "required_plan": "starter",
      "price": { "basis": "rate", "unit": "second", "estimated_charge": …, "estimated_charge_max": … }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

| Field | Type | Description |
| - | - | - |
| `object` | `string` | Always "model". Always `model`. |
| `id` | `string` | Pass as `model` to POST /v1/jobs. |
| `name` | `string` | The model's display name. |
| `type` | `string` | The kind of output it makes. One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. |
| `summary` | `string` or `null` | One line on what the model is. |
| `best_for` | `string` or `null` | What the model is good for. |
| `default` | `boolean` | Whether this is Voyager's recommended model for its type (a suggestion only: `model` is always required). |
| `status` | `string` | active, preview or retired. |
| `operations` | array of `string` | Operations this model runs, e.g. text-to-image, edit. |
| `available` | `boolean` or `null` | Whether this workspace can run it now; null when not known (decided when the job is accepted). |
| `unavailable_reason` | `string` or `null` | Why not, when available is false. One of `plan_locked`, `access_required`, `access_pending`, `access_denied`, `update_required`, `unavailable`, `retired`. |
| `required_plan` | `string` or `null` | The lowest Voyager plan that runs it, when known. |
| `price` | `Price` or `null` | Expected charge; null when not known. POST /v1/estimate is authoritative. |

`price` is an expected charge in Voyager credits per `unit`, never a cap. Use [`POST /v1/estimate`](https://docs.voyager.so/api/jobs#credits) for your exact request; prices are on [voyager.so/pricing](https://voyager.so/pricing).

| Field | Type | Description |
| - | - | - |
| `basis` | `string` | rate: an exact per-unit charge; example: the charge at the settings in points\[].when. One of `rate`, `example`. |
| `unit` | `string` | What one charge buys: image, second, video, request, 1k\_chars, minute, track… |
| `estimated_charge` | `number` or `null` | Expected credits per unit at the cheapest listed settings. An estimate, never a cap. |
| `estimated_charge_max` | `number` or `null` | Expected credits per unit at the dearest. |

## Read a model

```bash theme={"system"}
curl https://api.voyager.so/v1/models/example-video-model \
  -H "Authorization: Bearer $VOYAGER_API_KEY"
```

The response adds `operation_details`: for each operation, the JSON Schema of `input`, its defaults and a ready-to-send example, plus price detail. Again an illustrative example:

```json theme={"system"}
{
  "id": "example-video-model",
  "object": "model",
  "name": "Example Video Model",
  "type": "video",
  "default": false,
  "status": "active",
  "operations": ["text-to-video", "image-to-video"],
  "available": true,
  "unavailable_reason": null,
  "required_plan": "starter",
  "operation_details": [
    {
      "operation": "text-to-video",
      "input_schema": {
        "type": "object",
        "required": ["prompt"],
        "properties": {
          "prompt": { "type": "string" },
          "duration_seconds": { "type": "integer", "enum": [5, 10] },
          "aspect_ratio": { "type": "string", "enum": ["16:9", "9:16", "1:1"] },
          "cast": { "type": "array", "maxItems": 4, "items": { "type": "string" } }
        },
        "additionalProperties": false
      },
      "defaults": { "duration_seconds": 5, "aspect_ratio": "16:9" },
      "example": { "model": "example-video-model", "operation": "text-to-video", "input": { "prompt": "a paper boat drifting down a rainy street" } }
    },
    {
      "operation": "image-to-video",
      "input_schema": {
        "type": "object",
        "required": ["prompt", "image"],
        "properties": {
          "prompt": { "type": "string" },
          "image": { "type": "string", "contentMediaType": "image/*", "description": "A file_ id from POST /v1/files, or an https URL." }
        },
        "additionalProperties": false
      },
      "defaults": {},
      "example": { "model": "example-video-model", "operation": "image-to-video", "input": { "prompt": "the boat drifts away", "image": "file_…" } }
    }
  ],
  "price": { "basis": "rate", "unit": "second", "estimated_charge": …, "estimated_charge_max": …, "points": [ { "credits": …, "when": { "duration_seconds": 5 } } ], "as_of": "2026-11-05" }
}
```

The example is illustrative: its values aren't real limits. Model detail fields:

| Field | Type | Description |
| - | - | - |
| `object` | `string` | Always "model". Always `model`. |
| `id` | `string` | Pass as `model` to POST /v1/jobs. |
| `name` | `string` | The model's display name. |
| `type` | `string` | The kind of output it makes. One of `image`, `video`, `speech`, `music`, `sound_effect`, `3d`, `segment`. |
| `summary` | `string` or `null` | One line on what the model is. |
| `best_for` | `string` or `null` | What the model is good for. |
| `default` | `boolean` | Whether this is Voyager's recommended model for its type (a suggestion only: `model` is always required). |
| `status` | `string` | active, preview or retired. |
| `operations` | array of `string` | Operations this model runs, e.g. text-to-image, edit. |
| `available` | `boolean` or `null` | Whether this workspace can run it now; null when not known (decided when the job is accepted). |
| `unavailable_reason` | `string` or `null` | Why not, when available is false. One of `plan_locked`, `access_required`, `access_pending`, `access_denied`, `update_required`, `unavailable`, `retired`. |
| `required_plan` | `string` or `null` | The lowest Voyager plan that runs it, when known. |
| `price` | `PriceDetail` or `null` | Expected charge; null when not known. |
| `operation_details` | array of `ModelOperation` | Each operation's input schema, defaults and an example request. |

Each entry in `operation_details`:

| Field | Type | Description |
| - | - | - |
| `operation` | `string` | The operation. |
| `input_schema` | `object` | JSON Schema of `input` for this operation. |
| `defaults` | `object` | Values used for inputs you leave out. |
| `example` | `object` | A ready-to-send POST /v1/jobs body. |
| `cast_capabilities` | `object` or `null` | With X-Voyager-Cast-Version: 1: what Elements (input.cast) do on this operation — strategy, limits, prompt fallback and policies. Absent otherwise. |

Price detail:

| Field | Type | Description |
| - | - | - |
| `basis` | `string` | rate: an exact per-unit charge; example: the charge at the settings in points\[].when. One of `rate`, `example`. |
| `unit` | `string` | What one charge buys: image, second, video, request, 1k\_chars, minute, track… |
| `estimated_charge` | `number` or `null` | Expected credits per unit at the cheapest listed settings. An estimate, never a cap. |
| `estimated_charge_max` | `number` or `null` | Expected credits per unit at the dearest. |
| `points` | array of `PricePoint` | Expected charges at specific settings (when, in canonical input names). |
| `as_of` | `string` or `null` | Date the price was read. |

## Build a request

* **Pick an operation.** Pass `operation` on create. It's required when the model lists more than one in `operations`; only a single-operation model can leave it out. A missing or wrong one is `400` [`invalid_request`](https://docs.voyager.so/api/errors#invalid_request) with the model's operations in `details.operations`. Your plan never changes which operation runs: if it doesn't include the model, you get [`model_not_in_plan`](https://docs.voyager.so/api/errors#model_not_in_plan).
* **Start from `example`.** Each operation's `example` is a complete `POST /v1/jobs` body you can send as is.
* **Build `input` from that operation's `input_schema`.** Missing optional fields use its `defaults`. Validation is strict: an unknown field or a value the schema refuses is [`invalid_input`](https://docs.voyager.so/api/errors#invalid_input), before anything is charged.
* **Cast** works on image and video models whose `input_schema` has a `cast` field. See [Cast](https://docs.voyager.so/api/cast.md).

A job pins the model version and schema it was accepted with, so a later model update doesn't change a job already in flight.

### Input fields

`input` uses Voyager's own field names, the same on every model, whatever the model calls them. The table lists the shared fields. `GET /v1/models/{id}` serves each model's full input schema in these names: the shared fields it supports, with its own values, plus any settings of its own. Image sizes are `aspect_ratio` values (`"16:9"`, `"4:3"`, `"1:1"` and so on); a model that takes an exact size also has an `image_size` object with `width` and `height`. Media fields take a `file_…` ID from [uploads](https://docs.voyager.so/api/jobs.md#uploads) or an earlier output, or a public `https` URL, which Voyager imports into your workspace when the job is created. More fields and settings will be added over time.

| Field | Type | Description |
| - | - | - |
| `prompt` | `string` | The instruction; `caption` only where it is a string. |
| `negative_prompt` | `string` | Negative prompt. |
| `text` | `string` | The words spoken. |
| `aspect_ratio` | `string` | Unit: "W:H" or "auto". |
| `resolution` | `string` | Lowercase; others as-is. One of `360p`, `480p`, `540p`, `720p`, `768p`, `1080p`, `1440p`, `2k`, `4k`, `0.5k`, `1k`, `1.5k`. |
| `duration_seconds` | `number` | The model's values or range; "auto" where the model takes it. Unit: seconds. |
| `count` | `integer` | Count. |
| `seed` | `integer` | Seed. |
| `generate_audio` | `boolean` | Generate audio. |
| `voice_id` | `string` | Voice id. |
| `image` | `string` (image/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). |
| `images` | array of `string` (image/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). |
| `end_image` | `string` (image/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). |
| `video` | `string` (video/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). |
| `audio` | `string` (audio/\*) | A file\_ id from POST /v1/files, or an https URL (imported into your workspace first). |
| `cast` | any | API only: cst\_ ids, at most 4. |

## Voices

Speech models take a voice as `input.voice_id`, from `GET /v1/voices`: Voyager's premade voices, or your workspace's voice clones. A voice works only with the models in its `compatible_models`.

**Speech on Voyager's managed voices requires `voice_id`**: those models' `input_schema` marks it required, and a `tts` job without one is refused with `422` [`voice_required`](https://docs.voyager.so/api/errors#voice_required). Pick a voice whose `compatible_models` includes the model, and pass the words as `input.text`.

```bash theme={"system"}
curl "https://api.voyager.so/v1/voices?source=premade&q=warm" -H "Authorization: Bearer $VOYAGER_API_KEY"
```

Your own voice clones (`source=mine`) are on the Ultra and GigaMax plans ([`voice_cloning_unavailable`](https://docs.voyager.so/api/errors#voice_cloning_unavailable) otherwise); clones are made in the Voyager app.

| Parameter | Type | Description |
| - | - | - |
| `source` | `string` | premade: the managed catalog; mine: your voice clones in this workspace. One of `premade`, `mine`. Default `premade`. |
| `q` | `string` or `null` | Search premade voices. Up to 200 characters. |
| `language` | `string` or `null` | Up to 16 characters. |
| `gender` | `string` or `null` | Up to 16 characters. |
| `provider` | `string` or `null` | One of `elevenlabs`, `fishaudio`, `inworld`. |
| `limit` | `integer` | 1–100. Default `50`. |
| `cursor` | `string` or `null` | Up to 1024 characters. |

| Field | Type | Description |
| - | - | - |
| `object` | `string` | Always "voice". Always `voice`. |
| `id` | `string` | Pass as input.voice\_id to a speech job. |
| `name` | `string` or `null` | The voice's display name. |
| `source` | `string` | premade (the model's own) or mine (made in this workspace). One of `premade`, `mine`. |
| `provider` | `string` or `null` | The engine it renders on. |
| `compatible_models` | array of `string` | Speech models that can use it. |
| `preview_url` | `string` or `null` | A short sample of the voice, when there is one. |
| `labels` | `object` or array of any | Descriptive labels (accent, age, gender...). |

## Related

* [Jobs and polling](https://docs.voyager.so/api/jobs.md)
* [Cast](https://docs.voyager.so/api/cast.md)
* [Plans and credits](https://docs.voyager.so/account/plans-and-credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.