Files, links and storage

A finished order returns its result in result.files[]. These are paths inside storage, not URLs: a GET on such a string returns nothing. Downloading always takes two steps: exchange the path for a temporary link, then download from the link.

Exchanging a path for a link

POST /storage/url takes the full path, exactly as it appears in the order, and returns data.url — a signed temporary link. It's the only public API operation that requires the orders.download scope: with a key that has orders.read + orders.write, the order is visible but the file won't download — 403 with no reason at all.

The link lives for a limited time (per the spec, about an hour) and is downloaded with a plain GET without the X-API-KEY header: the signature is already inside the URL. Don't store it in a database or hand it out for long — request it right before downloading. If it has expired, repeat POST /storage/url for the same path; the file itself isn't affected.

Two file containers, not one

Subtitles and alignment are not in files[]. An order has two independent flat arrays of path strings:

An element has no separate type field — the type is told apart by the extension and by the /service/ segment in the string itself. raw_chunk and metadata paths aren't visible to an API key consumer; an attempt to exchange such a path gives 403.

Recipe: download everything there is

The whole pipeline:

# 1. The order: the paths are in result, and the status must be terminal
curl -s "$BASE/orders/$ORDER_ID" -H "X-API-KEY: $KEY"

# 2. Every path from files[] AND from service_files[] is exchanged for a link
curl -s -X POST "$BASE/storage/url" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "path": "storage/501/orders/<ORDER_UUID>/output/final/result.mp3", "download": true }'
# → { "success": true, "data": { "url": "https://s3.lumean.app/…?X-Amz-Signature=…" } }

# 3. Download from data.url with a plain GET, without X-API-KEY
curl -sL -o result.mp3 "$URL"

You can also collect files from a partially_completed order: the successful chunks are already finished. A failed order (failed, compensated) has result equal to null — there's nothing to download, and there are no error details on the public surface either.

Retention: two levels and two deadlines

Order files are deleted by retention — by default 7 days after the transition to a terminal status (completed, result_delivered, failed, compensated, cancelled). There are two storage levels, and the per-chunk tracks disappear earlier than the finished result:

Deleted files can't be restored: the order record stays in the database, but the files themselves no longer exist. The only way to get the result again is POST /orders/{order}/retry, which creates a new order with the same parameters and is billed again.