VoiceStudioDocs
Cloud reference

Jobs

List Jobs

GET
/v1/jobs

Cursor-paged, Organization-scoped Job listing in newest-first keyset order with optional exact-match state, workflow, and client_reference filters. A scoped API credential needs jobs:read, and its Organization is the one stored on the verified credential: organization_id is optional and, when supplied, must equal that Organization. Any other well-formed organization_id returns the same masked 404 as an unavailable Organization, without a Membership lookup. A Keycloak bearer caller must supply organization_id, which its current PostgreSQL Membership authorizes; a missing or foreign Membership is masked as 404. No caller-selected Organization header grants access, and browser sessions cannot reach this operation.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Query Parameters

organization_id?string

Required for a Keycloak bearer caller. Optional for a scoped API credential; when supplied it must equal the credential's stored Organization. A malformed value is a 400 for either caller.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16
state?string

Value in

  • "queued"
  • "running"
  • "canceling"
  • "succeeded"
  • "failed"
  • "canceled"
workflow?string

Exact workflow name; lowercase letters, digits, '.', '_', and '-'.

Match^[a-z0-9._-]*$
Lengthlength <= 64
client_reference?string

Exact customer-supplied client reference; control characters are rejected.

Lengthlength <= 128
cursor?string
Lengthlength <= 512
limit?integer
Range1 <= value <= 100
Default25

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/jobs"
json
{
  "items": [
    {
      "id": "stringstringstri",
      "project_id": "stringstringstri",
      "workflow": "string",
      "state": "queued",
      "model_id": "string",
      "model_version": "string",
      "progress_permille": 0,
      "failure_code": "string",
      "client_reference": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

Create Job

POST
/v1/jobs

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string
Length16 <= length <= 128

Request Body

application/json

project_id*OpaqueId

Exactly 16 cryptographically random Base62 characters.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16
workflow*string
model*
input*

A verified text Artifact. Inline text remains unavailable until it is encrypted into a staged Artifact before durable admission.

configuration*
client_reference?string
Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/jobs" \
  -H "Idempotency-Key: stringstringstri" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "stringstringstri",
    "workflow": "tts",
    "model": {
      "id": "string",
      "version": "string"
    },
    "input": {
      "text_artifact_id": "stringstringstri"
    },
    "configuration": {
      "voice_id": "string",
      "output_format": "wav"
    }
  }'
json
{
  "job_id": "stringstringstri",
  "project_id": "stringstringstri",
  "state": "queued",
  "progress_permille": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Get Job

GET
/v1/jobs/{job_id}

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

job_id*string

Exactly 16 cryptographically random Base62 characters.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16

Response Body

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/jobs/stringstringstri"
json
{
  "id": "stringstringstri",
  "project_id": "stringstringstri",
  "workflow": "tts",
  "state": "queued",
  "model_id": "string",
  "model_version": "string",
  "progress_permille": 0,
  "output_artifact_ids": [
    "stringstringstri"
  ],
  "failure_code": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}

Get Job Transcript

GET
/v1/jobs/{job_id}/transcript

Read the committed transcription.v1 output as its versioned JSON document or a server-rendered text, SRT, or VTT view. API credentials require both jobs:read and artifacts:read; Job and Artifact ownership are checked separately. Authenticated browser sessions may reach this exact route through the dashboard gateway, which forwards its server-held identity and selected Organization. Responses are never cacheable.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

job_id*string

Exactly 16 cryptographically random Base62 characters.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16

Query Parameters

format?string
Default"json"

Value in

  • "json"
  • "text"
  • "srt"
  • "vtt"

Response Body

application/json

application/json

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/jobs/stringstringstri/transcript"
json
{
  "schema": "transcript.v2",
  "language": "string",
  "duration_seconds": 0,
  "segments": [
    {
      "start_seconds": 0,
      "end_seconds": 0,
      "text": "string",
      "confidence": 0,
      "words": [
        {
          "start_seconds": 0,
          "end_seconds": 0,
          "text": "string",
          "confidence": 0
        }
      ]
    }
  ]
}

Cancel Job

POST
/v1/jobs/{job_id}/cancel

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

job_id*string

Exactly 16 cryptographically random Base62 characters.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16

Header Parameters

Idempotency-Key*string
Length16 <= length <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/jobs/stringstringstri/cancel" \
  -H "Idempotency-Key: stringstringstri"
json
{
  "job_id": "stringstringstri",
  "project_id": "stringstringstri",
  "state": "queued",
  "progress_permille": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Stream Job Events

GET
/v1/jobs/{job_id}/events

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

job_id*string

Exactly 16 cryptographically random Base62 characters.

Match^[A-Za-z0-9]{16}$
Length16 <= length <= 16

Header Parameters

Last-Event-ID?string
Lengthlength <= 128

Response Body

text/event-stream

application/json

application/json

application/json

bash
curl -X GET "https://example.com/v1/jobs/stringstringstri/events"
json
"string"

Clone Voice

POST
/v1/voices/{voice_id}/clone

Admits asynchronous processing for one consented draft Voice. Scoped API credentials require both voices:write and jobs:write. The server stages its own bounded preview phrase; the tenant-RLS transaction revalidates the draft Voice, consented reference audio, duration, model, reservation, Job, and immutable Voice-to-Job link before committing. The target Voice ID never enters the GPU task snapshot.

Authorization

DeveloperCredential
AuthorizationBearer <token>

In: header

Path Parameters

voice_id*string
Match^[A-Za-z0-9_-]{16}$

Header Parameters

Idempotency-Key*string

Replay key for the Voice surface, which bounds keys at 512 characters rather than the 128 used elsewhere.

Length1 <= length <= 512

Request Body

application/json

project_id*string
Length1 <= length <= 128
model*

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

bash
curl -X POST "https://example.com/v1/voices/string/clone" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "string",
    "model": {
      "id": "string",
      "version": "string"
    }
  }'
json
{
  "job_id": "stringstringstri",
  "project_id": "stringstringstri",
  "state": "queued",
  "progress_permille": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Artifacts

Previous Page

Usage

Next Page