Models

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

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:

{
  "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 for your exact request; prices are on 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

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:

{
  "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 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.
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, before anything is charged.
Cast works on image and video models whose input_schema has a cast field. See Cast.

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 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. Pick a voice whose compatible_models includes the model, and pass the words as input.text.

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 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…).

Get started

Concepts

Reference

Cloud machines

API reference

List models

Read a model

Build a request

Input fields

Voices

​List models

​Read a model

​Build a request

​Input fields

​Voices

​Related

List models

Read a model

Build a request

Input fields

Voices

Related