Estimate a job

curl --request POST \
  --url https://api.voyager.so/v1/estimate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>"
}
'

import requests

url = "https://api.voyager.so/v1/estimate"

payload = { "model": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({model: '<string>'})
};

fetch('https://api.voyager.so/v1/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "model": "<string>",
  "operation": "<string>",
  "estimated_charge": 123,
  "required_hold": 123,
  "available_credits": 123,
  "can_run": true,
  "object": "estimate",
  "reason": "<string>",
  "upgrade_url": "<string>",
  "estimate_basis": "fallback",
  "estimate_source": "a",
  "cast_usage": {}
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

Estimate a job

What a job with this body would cost. Reserves nothing; null when unknown; not a price cap (the charge is the job’s real cost). can_run is false when the plan, model access or balance refuses it, or it is unknown.

An https URL in input is priced as it is (checked, never downloaded or stored). One exception: a source recording for a speech, voice or audio model, whose price depends on its length, is imported into your workspace to measure it (a reference file that expires after 7 days, like any imported reference); send a file_ id from POST /v1/files to avoid the import.

POST

estimate

Estimate a job

curl --request POST \
  --url https://api.voyager.so/v1/estimate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>"
}
'

import requests

url = "https://api.voyager.so/v1/estimate"

payload = { "model": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({model: '<string>'})
};

fetch('https://api.voyager.so/v1/estimate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "model": "<string>",
  "operation": "<string>",
  "estimated_charge": 123,
  "required_hold": 123,
  "available_credits": 123,
  "can_run": true,
  "object": "estimate",
  "reason": "<string>",
  "upgrade_url": "<string>",
  "estimate_basis": "fallback",
  "estimate_source": "a",
  "cast_usage": {}
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "retry_after_ms": 123,
    "param": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

A Voyager API key from https://voyager.so/dashboard/api.

Headers

Idempotency-Key

string | null

Accepted and validated; an estimate starts nothing.

X-Voyager-Cast-Version

string | null

1: input.cast takes saved cards with selections and inline packages, input.cast_policy and input.cast_plan, and answers carry cast_usage. Omit for today's string Cast.

Body

application/json

model

string

required

A model id from GET /v1/models.

Required string length: 1 - 200

operation

enum<string> | null

One of text-to-image, edit, text-to-video, image-to-video, reference-to-video, tts, music, sound-effects, text-to-3d, image-to-3d, image-to-3d-body, align-3d, segment-image, segment-image-data, segment-video, segment-video-data, segment-everything, image-embedding (GET /v1/models/{id} lists a model's). Required unless the model runs only one.

Available options:

text-to-image,

edit,

text-to-video,

image-to-video,

reference-to-video,

tts,

music,

sound-effects,

text-to-3d,

image-to-3d,

image-to-3d-body,

align-3d,

segment-image,

segment-image-data,

segment-video,

segment-video-data,

segment-everything,

image-embedding

input

JobInput · object

The model's canonical inputs: its input_schema on GET /v1/models/{id} (file_ ids or https URLs for media), plus optional cast (up to 4 cst_ ids) on image and video operations.

Show child attributes

webhook_url

string | null

Public https URL that receives job.succeeded / job.failed / job.canceled (Standard Webhooks).

Maximum string length: 2048

metadata

Metadata · object | null

Up to 16 string pairs echoed on the job and its webhooks (values ≤ 500 chars).

Show child attributes

Response

Successful Response

model

string

required

The model estimated.

operation

string

required

The operation estimated.

estimated_charge

number | null

required

Expected credits for this request; null when unknown.

required_hold

number | null

required

Credits held when the job is accepted, at today's prices; null when unknown.

available_credits

number | null

required

The workspace's credit balance, as its Voyager dashboard shows it; null when unknown.

can_run

boolean

required

False when the plan, access or balance refuses it, or it is unknown.

object

string

default:estimate

Always "estimate".

Allowed value: "estimate"

reason

string | null

Why not, as the error code a create would get: model_not_in_plan, model_access_required, insufficient_credits, credits_reloading (retry shortly), free_allowance_exhausted, free_window_limit, free_media_limit, paid_plan_required, no_voyager_seat, model_unavailable; estimate_unavailable when it could not be read.

upgrade_url

string | null

Where to upgrade the plan or add credits, when that is the reason.

estimate_basis

string | null

"fallback" when nothing prices this request and estimated_charge is its model's fallback rate (show it as an estimate); absent otherwise. A fallback figure never refuses the job.

Allowed value: "fallback"

estimate_source

enum<string> | null

With estimate_basis fallback, the rate's evidence: a its own settlements, b its provider's published price, c its own other prices scaled, d a peer model's, e its media type's default.

Available options:

a,

b,

c,

d,

e

cast_usage

Cast Usage · object | null

With X-Voyager-Cast-Version: 1 and input.cast: what the Elements compile to. Pass its plan as input.cast_plan to create the job only if the Elements still compile to it.

Get started

Concepts

Reference

Cloud machines

API reference

Estimate a job

Authorizations

Headers

Body

Response