voao pro public API

Version v1 · generated from the OpenAPI description the server is built from

Generate with voao pro's models from your own systems: list models, price a request, submit a job, be told when it ends and fetch the result. Authenticate with an API key (Authorization: Bearer vk_...).

Guides: authentication, idempotency, limits, webhooks and code samples. The machine-readable description is v1.yaml.

Authentication

Send an API key as Authorization: Bearer vk_<prefix>_<secret>. A key only reaches the operations its scopes allow; the scope each operation needs is named in its summary. Everything a key makes belongs to its workspace.

ScopeAllows
models:readList models and tools; ask a price
jobs:readGet and list jobs
jobs:writeSubmit and cancel jobs; ask a price
assets:readGet an asset; get a download link
assets:writeUpload files
usage:readRead API usage

Errors

Every error has the same shape; the code is stable within a version, the message is for people.

{"error": {"code": "insufficient_credits", "message": "...", "details": {}}}
StatusCodes
401unauthenticated (missing, malformed, unknown, revoked or expired key; no reason is given)
403not_allowed (the key's scopes do not allow it), model_locked (the plan does not include the model)
404not_found (also for objects of other workspaces)
409idempotency_key_reused, job_not_cancellable, org_read_only, insufficient_credits, spending_limit_reached, asset_not_ready, upload_not_open
422idempotency_key_required, invalid_job_input, unknown_model, invalid_upload, unsupported_file_type, asset_too_large, size_mismatch, upload_incomplete
429rate_limited (with Retry-After)
5xxinternal_error and other codes; safe to retry with the same Idempotency-Key

Every answer carries X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Models

GET /v1/models

The models the org's plan offers (scope models:read)

Models above the plan are listed with locked set and cannot be used. input_schema describes the settings a job of the model takes.

Responses

200 The models

ModelList

  • models array of ModelInfo required
    Fields

    Array of ModelInfo

    ModelInfo

    • key string required
    • name string required
    • kind ModelKind required one of image video audio text 3d
    • beta boolean required
    • locked boolean required
      The org's plan does not include this model
    • tab string one of asset scene
      The tab of the 3D Studio the model is in (only models of kind 3d have one)
    • result string one of file voice data
      What a job of the model makes - a file (the default), a saved voice or data (a text model); only a file can be passed on in a canvas
    • input_schema object required
      Free-form object.
    • ui_schema object required
      Free-form object.

default Error (standard error shape, see Errors)

Tools

GET /v1/tools

The tools the org's plan offers (scope models:read)

Responses

200 The tools

ToolList

  • tools array of ToolInfo required
    Fields

    Array of ToolInfo

    ToolInfo

    • key string required
    • name string required
    • kind ModelKind required one of image video audio text 3d
    • group string required one of image video audio analysis subtitles
    • order integer required
    • beta boolean required
    • locked boolean required
      The org's plan does not include this tool
    • result string one of file data
      Whether a run makes a new file or only data shown on the page
    • input_schema object required
      Free-form object.
    • ui_schema object required
      Free-form object.

default Error (standard error shape, see Errors)

Price

POST /v1/price

The price of a job before it is submitted (scope models:read or jobs:write)

Runs the checks and the pricing a submission runs and reserves nothing, so the number is the number a job of the same request would reserve.

Request body

PublicJobRequest

  • model string required
  • input object required
    The settings the model takes (see input_schema in the model list)
    Free-form object.

Responses

200 The price

PricePreview

  • price integer (int64) required

default Error (standard error shape, see Errors)

Jobs

GET /v1/jobs

The jobs made through API keys in the key's workspace, newest first (scope jobs:read)

Parameters

NameInTypeRequiredDescription
cursorquerystringno
limitqueryinteger (1..200)no
statusqueryJobStatus
queued submitted running finalizing succeeded failed blocked cancelled		no

Responses

200 A page of jobs

PublicJobPage

  • jobs array of PublicJob required
    Fields

    Array of PublicJob

    PublicJob

    • id string (uuid) required
    • model string required
    • status JobStatus required one of queued submitted running finalizing succeeded failed blocked cancelled
      finalizing means the provider has finished and the result is being saved; credits are settled only after.
    • price integer (int64) required
      Credits reserved, and settled when the job succeeds
    • input object required
      Free-form object.
    • result_asset_ids array of string (uuid)
      The files a succeeded job made, as asset ids; fetch them with the assets endpoints
    • error_code string
    • error_message string
    • queue_position integer
      Place in the queue (1 is next); only while queued
    • created_at string (date-time) required
    • submitted_at string (date-time)
    • started_at string (date-time)
    • finished_at string (date-time)
    • updated_at string (date-time) required
  • next_cursor string

default Error (standard error shape, see Errors)

POST /v1/jobs

Submit a generation job (scope jobs:write)

Prices the job, reserves its credits and queues it in one step. The Idempotency-Key header is required (up to 200 characters); the same key with the same request returns the job already made, the same key with a different request is idempotency_key_reused (409).

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringnoChosen by the client. A missing key is refused with idempotency_key_required (422).

Request body

PublicJobRequest

  • model string required
  • input object required
    The settings the model takes (see input_schema in the model list)
    Free-form object.

Responses

201 The job

PublicJob

  • id string (uuid) required
  • model string required
  • status JobStatus required one of queued submitted running finalizing succeeded failed blocked cancelled
    finalizing means the provider has finished and the result is being saved; credits are settled only after.
  • price integer (int64) required
    Credits reserved, and settled when the job succeeds
  • input object required
    Free-form object.
  • result_asset_ids array of string (uuid)
    The files a succeeded job made, as asset ids; fetch them with the assets endpoints
  • error_code string
  • error_message string
  • queue_position integer
    Place in the queue (1 is next); only while queued
  • created_at string (date-time) required
  • submitted_at string (date-time)
  • started_at string (date-time)
  • finished_at string (date-time)
  • updated_at string (date-time) required

default Error (standard error shape, see Errors)

GET /v1/jobs/{jobId}

One job of the key's workspace (scope jobs:read)

Parameters

NameInTypeRequiredDescription
jobIdpathstring (uuid)yes

Responses

200 The job

PublicJob

  • id string (uuid) required
  • model string required
  • status JobStatus required one of queued submitted running finalizing succeeded failed blocked cancelled
    finalizing means the provider has finished and the result is being saved; credits are settled only after.
  • price integer (int64) required
    Credits reserved, and settled when the job succeeds
  • input object required
    Free-form object.
  • result_asset_ids array of string (uuid)
    The files a succeeded job made, as asset ids; fetch them with the assets endpoints
  • error_code string
  • error_message string
  • queue_position integer
    Place in the queue (1 is next); only while queued
  • created_at string (date-time) required
  • submitted_at string (date-time)
  • started_at string (date-time)
  • finished_at string (date-time)
  • updated_at string (date-time) required

default Error (standard error shape, see Errors)

POST /v1/jobs/{jobId}/cancel

Cancel a job made through an API key (scope jobs:write)

A queued job is cancelled at once and its credits return; one already at the provider is left to finish. A finished job cannot be cancelled (job_not_cancellable).

Parameters

NameInTypeRequiredDescription
jobIdpathstring (uuid)yes

Responses

200 The job after the request

PublicJob

  • id string (uuid) required
  • model string required
  • status JobStatus required one of queued submitted running finalizing succeeded failed blocked cancelled
    finalizing means the provider has finished and the result is being saved; credits are settled only after.
  • price integer (int64) required
    Credits reserved, and settled when the job succeeds
  • input object required
    Free-form object.
  • result_asset_ids array of string (uuid)
    The files a succeeded job made, as asset ids; fetch them with the assets endpoints
  • error_code string
  • error_message string
  • queue_position integer
    Place in the queue (1 is next); only while queued
  • created_at string (date-time) required
  • submitted_at string (date-time)
  • started_at string (date-time)
  • finished_at string (date-time)
  • updated_at string (date-time) required

default Error (standard error shape, see Errors)

Assets

POST /v1/assets/uploads

Start uploading a file to use as a setting of a job (scope assets:write)

Request body

StartUploadRequest

  • name string required
  • content_type string required
  • size_bytes integer (int64) required

Responses

201 The upload to send

UploadPlan

  • asset_id string (uuid) required
  • part_size integer (int64) required
    Bytes per part except the last
  • part_count integer required

default Error (standard error shape, see Errors)

POST /v1/assets/{assetId}/upload/parts

Links for sending the named parts (scope assets:write)

Parameters

NameInTypeRequiredDescription
assetIdpathstring (uuid)yes

Request body

SignPartsRequest

  • parts array of integer required

Responses

200 The links

PartLinks

  • parts array of object required
    Fields

    Array of object

    • number integer required
    • url string required

default Error (standard error shape, see Errors)

POST /v1/assets/{assetId}/complete

Confirm an upload (scope assets:write)

Parameters

NameInTypeRequiredDescription
assetIdpathstring (uuid)yes

Request body

CompleteUploadRequest

  • parts array of object required
    Fields

    Array of object

    • number integer required
    • etag string required

Responses

200 The asset

Asset

  • id string (uuid) required
  • workspace_id string (uuid) required
  • kind AssetKind required one of image video audio subtitle model document
  • content_type string required
  • size_bytes integer (int64) required
  • duration_seconds number (double)
    The length of a video, or of a WAV or M4A recording, when it is known
  • width integer
    The width of a picture in pixels, when it is known
  • height integer
    The height of a picture in pixels, when it is known
  • name string required
  • source string required one of upload generated
  • job_id string (uuid)
  • created_by string (uuid) required
  • created_by_name string required
  • created_at string (date-time) required
  • url string
    A link to view or play the file; works until url_expires_at. Re-request the asset for a fresh one.
  • url_expires_at string (date-time)
  • project_ids array of string (uuid)
    The projects this asset is in

default Error (standard error shape, see Errors)

GET /v1/assets/{assetId}

One asset of the key's workspace (scope assets:read)

Parameters

NameInTypeRequiredDescription
assetIdpathstring (uuid)yes

Responses

200 The asset

Asset

  • id string (uuid) required
  • workspace_id string (uuid) required
  • kind AssetKind required one of image video audio subtitle model document
  • content_type string required
  • size_bytes integer (int64) required
  • duration_seconds number (double)
    The length of a video, or of a WAV or M4A recording, when it is known
  • width integer
    The width of a picture in pixels, when it is known
  • height integer
    The height of a picture in pixels, when it is known
  • name string required
  • source string required one of upload generated
  • job_id string (uuid)
  • created_by string (uuid) required
  • created_by_name string required
  • created_at string (date-time) required
  • url string
    A link to view or play the file; works until url_expires_at. Re-request the asset for a fresh one.
  • url_expires_at string (date-time)
  • project_ids array of string (uuid)
    The projects this asset is in

default Error (standard error shape, see Errors)

GET /v1/assets/{assetId}/download

A signed, expiring link to the delivered file (scope assets:read)

A generated picture or video is delivered with the org's copyright notice and a mark id in its metadata, and with a visible watermark unless the plan removes it. A video's marked copy is made first: until it is ready the answer is 202; ask again.

Parameters

NameInTypeRequiredDescription
assetIdpathstring (uuid)yes

Responses

200 The link

DownloadLink

  • url string required
  • expires_at string (date-time) required
  • marked boolean
    True when the file carries a visible watermark

202 The marked copy is being prepared; ask again shortly

DownloadPreparing

  • state string required one of preparing

default Error (standard error shape, see Errors)

Usage

GET /v1/usage

Usage of API keys by day (scope usage:read)

Jobs made through API keys in the key's workspace, per day (UTC) and key, for up to a year.

Parameters

NameInTypeRequiredDescription
fromquerystring (date)noFirst day (UTC, YYYY-MM-DD); defaults to 30 days before to
toquerystring (date)noLast day (UTC, YYYY-MM-DD, included); defaults to today. The period is at most one year.

Responses

200 The usage

ApiUsage

  • from string (date) required
  • to string (date) required
  • rows array of ApiUsageRow required
    Fields

    Array of ApiUsageRow

    ApiUsageRow

    • day string (date) required
    • api_key_id string (uuid) required
    • api_key_name string required
    • workspace_id string (uuid) required
    • jobs integer (int64) required
    • succeeded integer (int64) required
    • failed integer (int64) required
    • blocked integer (int64) required
    • cancelled integer (int64) required
    • credits integer (int64) required
      Credits settled by the succeeded jobs
  • totals object required
    Fields
    • jobs integer (int64) required
    • succeeded integer (int64) required
    • failed integer (int64) required
    • blocked integer (int64) required
    • cancelled integer (int64) required
    • credits integer (int64) required

default Error (standard error shape, see Errors)