Cloud public API preview
The unreleased Cloud developer API, with Artifacts in and durable Jobs out.
Cloud API is not released
This is a contract preview, not a place to send production traffic. The
OpenAPI document has no server, and examples use the placeholder
$VOICESTUDIO_CLOUD_ORIGIN.
| Provenance | Value |
|---|---|
| Product | VoiceStudio Cloud public developer API |
| Audience | Public developer credentials only |
| Contract version | 1.0.0 |
| Generated contract version | 1.0.0 |
| Source repository | debpalash/vssaas |
| Source commit | c48c41f8fe5bb4496a9d218c513fd91fe827c0b5 |
| Raw public projection | /cloud-openapi.json |
It contains 34 developer operations. Dashboard, operator and internal operations are excluded, along with the schemas only they use.
How work runs
Cloud work is not a direct call. Inputs become immutable Artifacts, then an
authenticated request admits a durable Job and returns at once. Every mutation
takes a caller-made Idempotency-Key: the same key and body return the same
outcome, and a changed body is a conflict.
A non-executable preview. It does not name a production host:
export VOICESTUDIO_CLOUD_ORIGIN="https://unreleased.invalid"
export VOICESTUDIO_API_KEY="vs_preview_only"
# 1. Ask to upload the exact text bytes.
curl "$VOICESTUDIO_CLOUD_ORIGIN/v1/artifacts/upload-authorizations" \
-H "Authorization: Bearer $VOICESTUDIO_API_KEY" \
-H "Idempotency-Key: 018f-example-upload-key" \
-H "Content-Type: application/json" \
-d '{
"project_id": "replace-with-project-id",
"purpose": "tts_text",
"media_type": "text/plain; charset=utf-8",
"size_bytes": 24,
"sha256": "replace-with-64-lowercase-hex-characters"
}'
# 2. PUT the bytes to the returned short-lived URL, then complete the Artifact.
curl "$VOICESTUDIO_CLOUD_ORIGIN/v1/artifacts/ARTIFACT_ID/complete" \
-H "Authorization: Bearer $VOICESTUDIO_API_KEY" \
-H "Idempotency-Key: 018f-example-complete-key" \
-H "Content-Type: application/json" \
-d '{ "size_bytes": 24, "sha256": "replace-with-64-lowercase-hex-characters" }'
# 3. Admit a Job. Success is 202 Accepted, not audio.
curl "$VOICESTUDIO_CLOUD_ORIGIN/v1/jobs" \
-H "Authorization: Bearer $VOICESTUDIO_API_KEY" \
-H "Idempotency-Key: 018f-example-job-key" \
-H "Content-Type: application/json" \
-d '{
"project_id": "replace-with-project-id",
"workflow": "tts",
"model": { "id": "replace-with-model-id", "version": "replace-with-version" },
"input": { "text_artifact_id": "replace-with-artifact-id" },
"configuration": { "voice_id": "replace-with-voice-id", "output_format": "wav" }
}'The 202 Accepted body carries the Job's identity and state. Poll
GET /v1/jobs/{job_id} or resume GET /v1/jobs/{job_id}/events, then fetch the
output through an Artifact download authorization. Access always comes from the
credential and tenant membership; an ID in a request never grants it.
Exact schemas: the Cloud API reference.