Deliver job results to your storage

By default an async or batch job keeps its results in Inworld storage for about 7 days and hands you signed URLs to download them. Results delivery turns that around: you give the job a URL to your own bucket, pre-signed for upload, and the job writes its results there as one zip archive. Your results only pass through Inworld on the way to your storage and are not retained, and the job is billed once the upload succeeds.

It works with any cloud whose storage issues pre-signed upload URLs — Amazon S3 and S3-compatible services, Google Cloud Storage and Azure Blob Storage — and needs no credentials of yours on Inworld's side. The URL is the whole authorization, and it is yours to mint, scope and expire.

How it works

# RESULTS_URI holds a URL you pre-signed for PUT (see "Minting a URL").
# It carries a signature, so keep it out of logs and shell history.

# 1. Submit
OPERATION=$(curl -s 'https://api.inworld.ai/tts/v1/voice:synthesizeAsync' \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "$(jq -n --arg uri "$RESULTS_URI" '{
    text: "Hello, world! What a wonderful day to be a text-to-speech model!",
    voiceId: "Dennis",
    modelId: "inworld-tts-2",
    audioConfig: { audioEncoding: "MP3" },
    timestampType: "WORD",
    outputConfig: { resultsUri: $uri }
  }')" | jq -r '.name')

# 2. Poll until done: true
until curl -s "https://api.inworld.ai/lro/v1alpha/$OPERATION" \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  | tee operation.json | jq -e '.done == true' > /dev/null; do
  sleep 5
done

# 3. The archive is in your bucket. resultsUri names it without the signature.
jq '.response' operation.json
# {
#   "resultsUri": "https://my-bucket.s3.us-east-2.amazonaws.com/tts/job-42.zip",
#   "resultsPath": "results.json"
# }

import json
import os
import time
import zipfile

import requests

BASE = "https://api.inworld.ai"
HEADERS = {"Authorization": "Basic <api-key>"}

# A URL you pre-signed for PUT (see "Minting a URL"). It carries a signature,
# so keep it out of logs.
results_uri = os.environ["RESULTS_URI"]

# 1. Submit
operation = requests.post(
    f"{BASE}/tts/v1/voice:synthesizeAsync",
    headers=HEADERS,
    json={
        "text": "Hello, world! What a wonderful day to be a text-to-speech model!",
        "voiceId": "Dennis",
        "modelId": "inworld-tts-2",
        "audioConfig": {"audioEncoding": "MP3"},
        "timestampType": "WORD",
        "outputConfig": {"resultsUri": results_uri},
    },
).json()

# 2. Poll
while not operation.get("done"):
    time.sleep(5)
    operation = requests.get(
        f"{BASE}/lro/v1alpha/{operation['name']}", headers=HEADERS
    ).json()
if "error" in operation:
    raise RuntimeError(f"Job failed: {operation['error']['message']}")

# 3. The archive is in your bucket at operation["response"]["resultsUri"].
#    Fetch it with your own storage SDK or CLI, then read it:
archive = zipfile.ZipFile("job-42.zip")
results = json.loads(archive.read(operation["response"]["resultsPath"]))
audio = archive.read(results["audioPath"])

What the archive contains

resultsPath is always results.json today; read it from the response rather than assuming the name, so the layout can gain a version without breaking your integration. Every path in the document is relative to the document itself, so it resolves against the same archive.

An async job's archive:

results.json
audio.mp3            # or the extension of the encoding you requested
timestamps.json      # only when timestampType was requested

with results.json, the results document, holding the artifact paths:

{ "audioPath": "audio.mp3", "timestampsPath": "timestamps.json" }

A batch's archive holds one entry per successful item, addressed by the item's position in the request:

results.json
items/0.mp3
items/0.timestamps.json
items/1.mp3
...

and results.json is the same results file a hosted batch produces, with paths in place of signed URLs. Correlate by customId, never by position:

{
  "totalItems": 3,
  "completedItems": 2,
  "failedItems": 1,
  "results": [
    {"customId": "chapter-01", "audioPath": "items/0.mp3", "timestampsPath": "items/0.timestamps.json"},
    {"customId": "chapter-02", "audioPath": "items/1.mp3"},
    {"customId": "chapter-03", "error": {"code": 3, "message": "text exceeds per-item limit"}}
  ]
}

A failed item has no files in the archive; its error is in the document. Every timestamps file has the form described in Reading the timestamps document. Audio is stored uncompressed inside the zip and JSON documents are deflated, so the archive is about the size of the audio it holds.

Minting a URL

Mint the URL from your own credentials, for a PUT to the exact object the archive should be written to. Each URL is single-use in practice: the job overwrites the probe's empty object with the archive, so give every job its own object name.

import boto3
from botocore.config import Config

region = "us-east-2"
s3 = boto3.client(
    "s3",
    region_name=region,
    endpoint_url=f"https://s3.{region}.amazonaws.com",
    config=Config(signature_version="s3v4", s3={"addressing_style": "virtual"}),
)
results_uri = s3.generate_presigned_url(
    "put_object",
    Params={"Bucket": "my-bucket", "Key": "tts/job-42.zip"},
    ExpiresIn=3 * 24 * 3600,  # seconds; at most 7 days
)

from datetime import timedelta

from google.cloud import storage

blob = storage.Client().bucket("my-bucket").blob("tts/job-42.zip")
results_uri = blob.generate_signed_url(
    version="v4",
    method="PUT",
    expiration=timedelta(days=3),  # at most 7 days
)

from datetime import datetime, timedelta, timezone

from azure.storage.blob import BlobSasPermissions, generate_blob_sas

account, container, blob = "myaccount", "tts", "job-42.zip"
sas = generate_blob_sas(
    account_name=account,
    container_name=container,
    blob_name=blob,
    account_key="<account key>",
    permission=BlobSasPermissions(create=True, write=True),
    expiry=datetime.now(timezone.utc) + timedelta(days=3),
)
results_uri = f"https://{account}.blob.core.windows.net/{container}/{blob}?{sas}"

Checks at submit

Everything about the destination is checked before an operation exists, so a bad URL costs a submit call, never synthesis time. In order:

The size check runs before the probe, so a job refused for size leaves nothing in your bucket.

When delivery fails

The upload runs after synthesis. A transient failure — a 429, a 5xx, a dropped connection — is retried for a bounded window. Anything the destination will keep refusing ends the job: a 4xx, a redirect, a URL whose signature lapsed before the results were ready. The operation then carries an error:

A job whose delivery fails is not billed and nothing of it is retained, so the synthesis is redone on resubmit.

Packaging

outputConfig.packaging chooses between one archive and one file per artifact:

A delivered job and a hosted job with packaging: ZIP produce the same archive, so one integration that reads resultsUri and resultsPath serves both. A hosted job with the default FILES packaging keeps the per-artifact URLs described on the async and batch pages, with no resultsPath.

Limits

How much text fits

Submit estimates the archive from your text, speaking rate and encoding, and refuses a job whose estimate exceeds the destination's single-upload limit. The estimate errs high on purpose, so these are the most characters one job can carry to each destination at speaking rate 1.0:

Chinese and Japanese characters and Korean syllable blocks each take longer to speak than a letter, so fewer fit. A slower speaking rate lowers every figure in proportion: at 0.5, half as many fit. An async job carries at most 100,000 characters, so only a legacy-version Azure SAS can refuse one for size. For a batch, the request size and your queued-character budget usually bind well before these figures.

API reference