OpenAPI 3 — Create voice job (v1)
This page mirrors the human-readable reference for POST /v1/voice/jobs only. It provides a draft OpenAPI 3 contract (YAML below) that you can copy, validate with OpenAPI tooling, or open in Swagger UI.
The same specification is available in Scalar as the Interactive OpenAPI Reference.
Portfolio note: Values and hostnames are anonymized, consistent with the companion API reference doc.
Specification (YAML)
Requests must use Content-Type: application/json; in this OpenAPI document that requirement is expressed through requestBody in the spec, not as a separate header parameter.
Raw spec: /openapi/voice-jobs.yaml
voice-jobs.yaml
openapi: 3.0.3
info:
title: Voice Render API
version: 1.0.0
license:
name: Proprietary
description: |
Convert text to speech as a single synthesis job (v1).
Requests must use a Bearer access token and an idempotency key.
Idempotency keys are retained for 24 hours; reuse the same key only when retrying the identical request body.
servers:
- url: https://api.example.com
description: Example host (anonymized for portfolio)
tags:
- name: Voice jobs
description: Create and manage voice synthesis jobs
paths:
/v1/voice/jobs:
post:
tags:
- Voice jobs
operationId: createVoiceJob
summary: Create a voice job
description: |
Validates the request, applies policy checks, reserves quota, and enqueues a rendering job.
On success, returns a job_id for polling and audio retrieval.
security:
- bearerAuth: []
parameters:
- name: Idempotency-Key
in: header
required: true
description: |
UUID (v4) used to prevent duplicate job creation during retries.
Must be a valid UUID v4; missing or malformed values return 400 with invalid_input.
Use a new UUID for each new logical job; reuse the same UUID only when retrying the identical request body (for example, after a timeout or network error).
schema:
type: string
format: uuid
example: 8b3f1c8e-3f2b-4ad2-9ef0-2a8c9b2a4f19
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVoiceJobRequest'
examples:
default:
summary: Example from API reference
value:
input:
content: Hello, world.
content_type: text/plain
voice:
profile_id: voice_en_us_001
style: neutral
rate: 1.0
output:
format: pcm_s16le
sample_rate_hz: 24000
client:
request_tag: msg-001
responses:
'201':
description: Job created; body contains the new job identifier.
headers:
X-Quota-Limit:
description: Quota limit for the current billing period (plan cap).
schema:
type: string
X-Quota-Remaining:
description: Remaining quota for the current billing period after this request.
schema:
type: string
X-Request-Id:
description: Server-generated identifier for this request.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVoiceJobResponse'
examples:
default:
value:
job_id: 5b2a5b7a-6c2d-4d40-9e7b-1f25c08e6a1f
'400':
description: |
Request invalid (missing or malformed headers such as Idempotency-Key or Content-Type, invalid JSON body,
missing fields, wrong types, constraint violations, plan limits, invalid UTF-8, or unsupported output parameters).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_input:
value:
error:
code: invalid_input
message: Request body is invalid.
retryable: false
'401':
description: Missing or invalid access token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthenticated:
value:
error:
code: unauthenticated
message: Missing or invalid access token.
retryable: false
'402':
description: Insufficient quota to create the job.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
quota_exceeded:
value:
error:
code: quota_exceeded
message: Insufficient quota.
retryable: false
'403':
description: Content rejected by policy.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
policy_blocked:
value:
error:
code: policy_blocked
message: Content rejected by policy.
retryable: false
'409':
description: Same Idempotency-Key reused with a different request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
idempotency_conflict:
value:
error:
code: idempotency_conflict
message: Idempotency key conflict.
retryable: false
'429':
description: Too many requests; honor Retry-After when present.
headers:
Retry-After:
description: Suggested delay before retry (when provided).
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
rate_limited:
value:
error:
code: rate_limited
message: Too many requests. Please retry after a short delay.
retryable: true
'503':
description: Temporary service or upstream failure; retry with exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
service_unavailable:
value:
error:
code: service_unavailable
message: Service temporarily unavailable.
retryable: true
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Access token from your identity provider.
schemas:
CreateVoiceJobRequest:
type: object
additionalProperties: false
required:
- input
- voice
- output
properties:
input:
$ref: '#/components/schemas/VoiceJobInput'
voice:
$ref: '#/components/schemas/VoiceJobVoice'
output:
$ref: '#/components/schemas/VoiceJobOutput'
client:
$ref: '#/components/schemas/VoiceJobClient'
VoiceJobInput:
type: object
additionalProperties: false
required:
- content
- content_type
properties:
content:
type: string
minLength: 1
maxLength: 2000
description: UTF-8 text to synthesize; avoid control characters outside standard whitespace.
content_type:
type: string
enum:
- text/plain
VoiceJobVoice:
type: object
additionalProperties: false
required:
- profile_id
properties:
profile_id:
type: string
description: Voice profile identifier.
example: voice_en_us_001
style:
type: string
default: neutral
description: |
Rendering style. Allowed values are defined per voice profile.
Retrieve a profile (including supported styles) with GET /v1/voice/profiles/{profile_id},
or list all profiles with GET /v1/voice/profiles.
rate:
type: number
minimum: 0.5
maximum: 2.0
default: 1.0
description: Speed multiplier.
VoiceJobOutput:
type: object
additionalProperties: false
required:
- format
- sample_rate_hz
properties:
format:
type: string
enum:
- pcm_s16le
sample_rate_hz:
type: integer
example: 24000
enum:
- 8000
- 16000
- 22050
- 24000
- 44100
description: Sample rate in Hz. Other values return 400 with invalid_input.
VoiceJobClient:
type: object
additionalProperties: false
properties:
request_tag:
type: string
maxLength: 128
description: |
Optional client-defined correlation string (UTF-8, no required format).
If provided, echoed on the job resource from GET /v1/voice/jobs/{job_id}.
CreateVoiceJobResponse:
type: object
additionalProperties: false
required:
- job_id
properties:
job_id:
type: string
format: uuid
description: Identifier for the created job (UUID v4).
ErrorResponse:
type: object
additionalProperties: false
required:
- error
properties:
error:
type: object
required:
- code
- message
- retryable
additionalProperties: false
properties:
code:
type: string
description: Stable machine-readable error code.
message:
type: string
description: Human-readable detail.
retryable:
type: boolean
description: Whether the client should retry without changing the request (subject to backoff and headers).