{
  "info": {
    "name": "VowelMarks Developer API v1",
    "description": "Server-side examples for the VowelMarks Persian reading API. Generation JSON bodies are limited to 32 KiB and 6,000 Unicode code points. Some origins sleep while idle, so a first request can take several extra seconds. Retry an uncertain timeout with the same Idempotency-Key and exact body. Basic asynchronous jobs, Basic MP3 events, and completed-audio HEAD/range requests are available in production. Premium asynchronous jobs remain a development/staging preview and return non-retryable 503 premium_speech_jobs_unavailable in production; synchronous Premium remains available at POST /v1/speech. Website streaming does not enable Premium API jobs. A Premium preview requires separate explicit enablement. When its provider streaming is disabled, it buffers and checkpoints provider sections, emits status but no audio events before completion, and publishes one finished WAV. Poll the accepted job. When provider streaming is enabled, an enabled Premium preview can emit raw pcm_s16le audio at 24 kHz mono. Its approximately 150-second target and estimated 180-second section-planning ceiling are not guaranteed audio-duration limits.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "base_url", "value": "https://api.vowelmarks.com" },
    { "key": "api_key", "value": "vm_test_replace_me" },
    { "key": "job_id", "value": "replace-with-speech-job-id" },
    { "key": "audio_url", "value": "paste-the-complete-signed-audio-url" }
  ],
  "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{api_key}}", "type": "string" }] },
  "item": [
    { "name": "Diacritize", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "postman-diacritize-001" }], "body": { "mode": "raw", "raw": "{\n  \"text\": \"من فارسی می‌خوانم\",\n  \"include_ezafe\": true\n}" }, "url": "{{base_url}}/v1/diacritize" } },
    { "name": "Pinglish", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "body": { "mode": "raw", "raw": "{\n  \"text\": \"من فارسی می‌خوانم\",\n  \"style\": \"readable\"\n}" }, "url": "{{base_url}}/v1/pinglish" } },
    { "name": "Translate", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }], "body": { "mode": "raw", "raw": "{\n  \"text\": \"من فارسی می‌خوانم\"\n}" }, "url": "{{base_url}}/v1/translate" } },
    { "name": "Basic speech", "request": { "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "postman-speech-001" }], "body": { "mode": "raw", "raw": "{\n  \"text\": \"من فارسی می‌خوانم\",\n  \"tier\": \"basic\",\n  \"voice\": \"kian\"\n}" }, "url": "{{base_url}}/v1/speech" } },
    { "name": "Queue Basic speech job", "request": { "description": "Production Basic job creation. Reuse the same Idempotency-Key and exact body after an uncertain timeout. Premium uses this same published request shape only in explicitly enabled development/staging previews; production returns non-retryable 503 premium_speech_jobs_unavailable before reserving allowance or starting work. If provider streaming is disabled for an enabled Premium preview, submit one client job and poll it for one finished WAV rather than requiring live audio events.", "method": "POST", "header": [{ "key": "Content-Type", "value": "application/json" }, { "key": "Idempotency-Key", "value": "postman-speech-job-001" }], "body": { "mode": "raw", "raw": "{\n  \"text\": \"من فارسی می‌خوانم\",\n  \"tier\": \"basic\",\n  \"voice\": \"kian\"\n}" }, "url": "{{base_url}}/v1/speech/jobs" } },
    { "name": "Read Basic speech job", "request": { "description": "Poll until succeeded, failed, or cancelled. Reading a succeeded job during its 24-hour lifetime returns a fresh one-hour signed audio URL.", "method": "GET", "url": "{{base_url}}/v1/speech/jobs/{{job_id}}" } },
    { "name": "Stream Basic speech job events", "request": { "description": "Production Server-Sent Events with MP3 audio when available. Live chunks currently come only from fresh Kian or Leyla synthesis; legacy voices and cache hits may produce zero audio events. An explicitly enabled Premium preview with provider streaming disabled also emits no audio events before completion, so treat status-only SSE as normal and poll for the finished WAV. A client disconnect does not cancel the Workflow. EOF is not success; require a complete event or poll terminal status.", "method": "GET", "header": [{ "key": "Accept", "value": "text/event-stream" }], "url": "{{base_url}}/v1/speech/jobs/{{job_id}}/events" } },
    { "name": "Cancel Basic speech job", "request": { "description": "Best effort and idempotent. A completed race remains succeeded and is charged normally.", "method": "POST", "url": "{{base_url}}/v1/speech/jobs/{{job_id}}/cancel" } },
    { "name": "Inspect completed audio", "request": { "description": "Paste the complete signed audio_url returned by speech. No Bearer key is sent.", "auth": { "type": "noauth" }, "method": "HEAD", "url": "{{audio_url}}" } },
    { "name": "Download completed audio range", "request": { "description": "Requests one byte range from the signed completed file. No Bearer key is sent.", "auth": { "type": "noauth" }, "method": "GET", "header": [{ "key": "Range", "value": "bytes=0-1023" }], "url": "{{audio_url}}" } },
    { "name": "Usage", "request": { "method": "GET", "url": "{{base_url}}/v1/usage" } }
  ]
}