Zum Inhalt
Lumean API

Beschreibungen auf Englisch

Die Oberfläche des Bereichs ist in Ihre Sprache übersetzt, Beschreibungen von Operationen, Schemata und Fehlern gibt es aber nur auf Russisch und Englisch — hier wird die englische Fassung angezeigt.
POST/orders/chunks/preview

Preview Chunk Split

Dry-run of the text-to-chunks split and cost calculation — without creating an order. The same computation POST /orders uses internally: check your split/price here before the real submission. Does not spend the key's token quota — preview is free.

Korrekturen an der Spezifikation · 2

  • Chunk preview is available with an API key

    The machine-readable llm.md §12 claims chunk preview is a web-cabinet endpoint that returns 401 for API keys. That is wrong: all three preview operations are part of the public surface and require the orders.read scope — as described by both the OpenAPI document and §7.1 of the very same llm.md. If an AI assistant cites §12, it is mistaken.

  • Billing for [whisper] and <break/> markup is inconsistent

    Three places in the spec state that markup tags ([whisper], <break/>) are not billed, while the description of billable_length states they are. Until the backend resolves this, assume the worst case and count markup characters into your cost estimate. The exact price of a given text comes from POST /orders/chunks/preview, which returns the length already computed.

A single ready envelope covers both the sync and async paths:

  • 200 status=ready — TTS text ≤ 50,000 characters (and any non-TTS text): the result is ready immediately, the body carries summary (totals for the whole text), the first page of chunks[], and page (pagination meta).
  • 202 status=processing — TTS text past the threshold: the calculation runs in the background, the body carries only preview_id. The result arrives as a .ready WebSocket event on the private-chunks.preview.{userId} channel (see POST /broadcasting/auth), or fetch it manually via GET /orders/chunks/preview/{previewId}.

Incremental re-preview: pass the previous response's preview_id as previous_preview_id along with the new input_text — only the edited neighborhood is recomputed, and the result is identical to a full recalculation.

Order settings: pass the same config_override you will send to POST /orders — the preview splits by the template config with it applied, exactly like the order (settings that affect the split apply here too). A value that order creation would reject with 422 is rejected by the preview as well.

Pauses/caps: exceeding the pause limits (>500 pauses, >3600s total, >10s single) or the order size (>1500 fragments) does NOT fail the request — you get summary.caps_ok=false + caps_exceeded. This is what sets preview apart from POST /orders, where the same overage returns 422.

The preview cache is shared with a web session of the same account (if the key owner also uses the website): the same text+template+mode, already computed in the browser, comes back instantly.

Required key permission: orders.read (preview does not mutate data — it is a read).

Auf dieser Seite(4)

Anfragekörper

application/jsonerforderlich

Chunk-preview parameters — a dry-run of the text-to-chunks split and its cost, without creating an order. Free of charge, does not spend the key's token quota.

Beispielkörper
{
  "template_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c",
  "task_type": "string",
  "input_text": "string",
  "previous_preview_id": "string",
  "text_hash": "string",
  "generation_mode": "default",
  "config_override": []
}

Felder

template_iderforderlich
uuid
string
input_texterforderlich
string
task_typeoptional
darf null sein
string
previous_preview_idoptional

The preview_id of a prior preview response, for incremental re-preview: only the edited neighborhood is recomputed. Works for sync texts (≤50,000 characters); for larger ones the edit still goes through a full async recalculation. If it has expired, just omit it — you get a full recalculation instead.

darf null sein
string
text_hashoptional

Not required for POST — the server computes the hash itself from input_text. Send it only if you already know it for some other reason; it is otherwise ignored here (used by GET /orders/chunks/preview for the preflight lookup instead).

darf null seinMuster: ^[a-f0-9]{64}$
string
generation_modeoptional

Generation mode — the same value accepted by config_override.generation_mode when creating an order. paragraph splits the text on blank lines first, and each paragraph becomes its own generation unit (see POST /orders for the full explanation). Omitted — a continuous split, the previous behavior.

darf null sein
Wertedefaultparagraph
string
config_overrideoptional

Generation settings on top of the template config — the same JSON object you will send to POST /orders. Settings that affect the split apply to the preview exactly as to the order; keys the service does not declare are dropped. Omitted — the split follows the template config alone.

object

Mögliche Antworten

200

Success. The payload is in data.

Beispiel für den Body
"string"
Felder der Antwort
successerforderlich

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean
messageerforderlich

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string
dataerforderlich

The response payload.

object
statuserforderlich

Always ready for a 200 response — the calculation is done.

Werteready
string
preview_iderforderlich

A content-based preview id (sha256 of text+template+mode+algorithm version). Use it for incremental re-preview (previous_preview_id) and for pagination (GET .../{previewId}).

string
summaryerforderlich

Totals for the whole text — not just the current page of chunks.

object
chunks_counterforderlich

Total number of chunks in the split.

integer
total_effective_lengtherforderlich

Total billable length across all chunks, in characters (pauses and stage directions are excluded).

integer
total_price_unitserforderlich

Total cost in tokens — the same amount POST /orders would charge for the identical text.

integer
voiced_lengtherforderlich

Actual voiced length BEFORE topping up to the minimum billable volume — for an honest character count display.

integer
min_billable_charserforderlich

The minimum billable volume (0 — no minimum). If voiced_length is below this threshold, the cost is still computed against the threshold.

integer
pause_counterforderlich

Number of pauses in the text ({{pause}}/<break/>). Pauses are free — excluded from the cost.

integer
total_pause_secondserforderlich

Total silence duration, in seconds.

number
caps_okerforderlich

The order sanity caps are not exceeded. false does NOT fail the preview (unlike POST /orders, where the same overage returns 422) — it is only a warning.

boolean
caps_exceedederforderlich

Which cap was exceeded: count (more than 500 pauses), single (one pause longer than 10s), total (total silence over 3600s) or chunks (the order yields more than 1500 fragments — more than the system can assemble into one file). null means the caps are fine.

darf null sein
string
voiced_emptyerforderlich

Nothing speakable is left in the text (only tags/pauses/stage directions). POST /orders with this text would return 422.

boolean
blocked_chunkserforderlich

Indexes of chunks whose text already tripped the content policy and sits in the blocklist. An empty array means no blocks.

array<integer>
has_blocked_contenterforderlich

Whether at least one chunk is blocked — the same thing as blocked_chunks !== [], as a boolean for convenience.

boolean
paragraphserforderlich

null means the preview is not paragraph-mode (the same generation_mode value used for orders drives this field). In paragraph mode, an aggregate per paragraph.

darf null sein
array<object>
Array-Element
paragraph_indexerforderlich

The paragraph's index, zero-based.

integer
chunks_counterforderlich

How many chunks fall inside this paragraph (a long paragraph can span several chunks).

integer
first_chunk_indexerforderlich

The cross-text index of the paragraph's first chunk — use it to locate the paragraph within the paginated data.chunks, even if its chunks landed on a different page.

integer
text_lengtherforderlich

The raw length of the paragraph text in characters, including tags/pauses.

integer
effective_lengtherforderlich

The paragraph's billable length — in paragraph mode the minimum billable volume is enforced PER PARAGRAPH, so short paragraphs can cost more than the same text split continuously.

integer
price_unitserforderlich

The paragraph's cost in tokens.

integer
paragraphs_counterforderlich

Number of paragraphs, or null outside paragraph mode. Stays a number even when paragraphs is collapsed by the WS cap.

darf null sein
integer
cost_lmcoptional

Cost in LMC (currency-independent base). The field may be ABSENT (not null) if the cost anchor could not be computed — this is best-effort and not critical for a preview.

number
cost_displayoptional

The cost converted to the account's display currency — the same multi-currency breakdown used across the public API (amount/amount_formatted per currency code). The field may be ABSENT if cost_lmc was not computed or the rate is unavailable.

darf null sein
object
chunkserforderlich

Only the CURRENT page (see data.page), not the full list — use pagination (GET .../{previewId}?page=) for the rest.

array<object>
Array-Element
indexerforderlich

The chunk's index across the whole text (does not reset at paragraph boundaries).

integer
texterforderlich

The chunk text exactly as the voice provider will receive it.

string
starterforderlich

The chunk's start offset (in characters) within the NORMALIZED input text — the same normalization POST /orders applies before splitting.

integer
enderforderlich

The chunk's end offset in the normalized text (half-open interval: end is exclusive).

integer
text_lengtherforderlich

The raw length of the chunk text in characters, INCLUDING tags/pauses.

integer
effective_lengtherforderlich

The chunk's billable length (pauses excluded, topped up to the minimum where applicable) — the sum across a page's chunks need not equal total_effective_length (which covers ALL chunks, not just this page).

integer
price_unitserforderlich

The chunk's cost in tokens.

integer
paragraph_indexerforderlich

The index of the paragraph this chunk belongs to, or null outside paragraph mode.

darf null sein
integer
pageerforderlich

Pagination meta for the CURRENT page of data.chunks.

object
current_pageerforderlich

The current page number, 1-based.

integer
per_pageerforderlich

The page size (how many chunks were requested, or the default).

integer
totalerforderlich

Total chunks in the split (across all pages).

integer
has_moreerforderlich

Whether more pages follow the current one.

boolean
202

Accepted for processing. The result arrives asynchronously.

Beispiel für den Body
"string"
Felder der Antwort
successerforderlich

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean
messageerforderlich

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string
dataerforderlich

The response payload.

object
statuserforderlich

Always processing for a 202 response — the calculation is running in the background.

Werteprocessing
string
preview_iderforderlich

The preview id. Use it to subscribe to the private-chunks.preview.{userId} WS channel (the .ready event), or to poll GET /orders/chunks/preview/{previewId} manually.

string
401

The key is missing, unknown, disabled or expired.

Diese Antwort analysieren
Beispiel für den Body
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Felder der Antwort
successerforderlich

Always false in error responses.

boolean
messageerforderlich

Error text in the key's language (set through the X-Locale header).

string
dataerforderlich

Always null when the request is rejected before processing.

darf null sein
null
403

The key lacks the required permission, or the object belongs to another user.

Diese Antwort analysieren
Beispiel für den Body
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Felder der Antwort
successerforderlich

Always false in error responses.

boolean
messageerforderlich

Error text in the key's language (set through the X-Locale header).

string
422

Validation error (input_text is required), or reason: template_model_outdated — the template or config_override carries settings of the service's previous schema, the same refusal as order creation (paths in fields).

Diese Antwort analysieren
Beispiel für den Body
{
  "message": "string",
  "errors": {
    "key": [
      "string"
    ]
  }
}
Felder der Antwort
messageerforderlich

Errors overview.

string
errorserforderlich

A detailed description of each field that failed validation.

object
*optional
beliebige Schlüssel
array<string>
429

Limit exceeded: either the key's request rate or its token quota. Retry no earlier than Retry-After.

Diese Antwort analysieren
Beispiel für den Body
{
  "success": false,
  "message": "Too many attempts. Please wait a moment and try again.",
  "reason": "rate_limit_exceeded",
  "error_code": "rate_limit_exceeded",
  "retry_after": 30
}
Felder der Antwort
successerforderlich

Always false in error responses.

boolean
messageerforderlich

Error text in the key's language (set through the X-Locale header).

string
reasonerforderlich

Machine-readable failure reason — branch on this, not on the message text.

string
error_codeerforderlich

The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.

string
retry_afteroptional

How many seconds to wait before retrying (the same value is in the Retry-After header).

darf null sein
integer

Ereignisse, die dabei entstehen

Der Fortschritt kommt über WebSocket: Der Auftrag muss nicht in einer Schleife abgefragt werden. Das Abonnement braucht dasselbe Recht wie das Lesen von Aufträgen.

Diese Seite einer KI geben

.md öffnenllm.md

Spezifikation 0.0.1