Studio

Audiobooks: a manuscript of chapters is narrated chapter by chapter in the background. Each finished chapter is a separate MP3 you can play while the rest of the book records.

Each read of the job records the next few parts, so the audiobook only moves forward while you poll.

Endpoints:

GET /v1/studio/options
POST /v1/studio/audiobooks
GET /v1/studio/audiobooks/{id}
GET /v1/studio/audiobooks/{id}/files/{name}

Get studio options

GET /v1/studio/options

Response

200 OK

json

{
  "limits": {
    "characters": 500000,
    "chapters": 200,
    "chapterCharacters": 30000,
    "paragraphCharacters": 20000,
    "minSpeed": 0.8,
    "maxSpeed": 1.2
  },
  "models": [
    { "id": "speech", "label": "Cinara Speech", "creditsPerCharacter": 1 },
    { "id": "speech-hd", "label": "Cinara Speech HD", "creditsPerCharacter": 2 }
  ],
  "languages": ["auto", "English", "Hindi", "Spanish"]
}

languages is the same list as the speech options (shortened above).

Credits

Free.

Example

bash

curl https://api.cinara.ai/v1/studio/options \
  -H "Authorization: Bearer $CINARA_API_KEY"

Create an audiobook

POST /v1/studio/audiobooks

Starts narrating a manuscript.

Needs a verified phone.

The workspace's pronunciation rules are applied.

Request body

Field	Type	Required	Description
`chapters`	object[]	yes	The book, in order. Chapters with no text are skipped.
`chapters[].title`	string	no	Up to 200 characters. Default `Chapter <n>`.
`chapters[].paragraphs`	string[]	yes	The chapter's paragraphs, each up to 20,000 characters. Line breaks and runs of spaces inside a paragraph become single spaces. Blank paragraphs are dropped.
`voiceId`	string	yes	The narrator: a library voice id, or a workspace voice's `providerVoiceId`.
`model`	string	no	`speech` (default) or `speech-hd`.
`speed`	number	no	0.8–1.2. Default 1.
`language`	string	no	A language from the speech options. Anything else is `auto`.
`readTitles`	boolean	no	Read each chapter's title before it. Default `true`.
`title`	string	no	The book's title, up to 200 characters. Default `Untitled audiobook`.
`author`	string	no	Up to 120 characters.

Limits:

Chapters over 30,000 characters are split between paragraphs into Title (part 2), Title (part 3) and so on.
Up to 200 chapters after splitting.
Up to 500,000 spoken characters. A read title counts its length plus 1.

Response

201 Created

json

{
  "generation": {
    "id": "e9c3a7f1-4d8b-4b2e-a5c6-7f0d3b9e1a84",
    "module": "studio",
    "status": "running",
    "input": {
      "title": "The Lighthouse Keeper",
      "author": "R. Ellison",
      "fileName": "the-lighthouse-keeper.mp3",
      "voiceId": "hearth",
      "voiceName": "Hearth · Margaret",
      "model": "speech",
      "speed": 1,
      "language": "English",
      "readTitles": true,
      "characters": 118420
    },
    "output": {
      "phase": "speak",
      "stage": "processing",
      "stageLabel": "Recording chapter 1 of 12",
      "chapters": [
        { "title": "The Harbour", "characters": 9812, "parts": 3, "doneParts": [] },
        { "title": "The Storm", "characters": 10240, "parts": 3, "doneParts": [] }
      ],
      "partsTotal": 34,
      "partsDone": 0
    },
    "credits": 118420,
    "error": null,
    "created_at": "2026-09-15T21:30:12.445019+00:00",
    "completed_at": null
  },
  "credits": 81580
}

output.chapters is shortened above. Each chapter lists its spoken characters, how many parts it's recorded in, and which parts are done.

Errors

Status	`error`	Message
400	`invalid_request`	`Choose a voice model`
400	`invalid_request`	`Choose a narrator voice`
400	`invalid_request`	`Choose a speed from 0.8× to 1.2×`
400	`invalid_request`	`Keep each paragraph under 20,000 characters`
400	`invalid_request`	`Add the book's text`
400	`invalid_request`	`An audiobook can have up to 200 chapters`
400	`invalid_request`	`An audiobook can have up to 500,000 characters; this one has 512,044`
402	`insufficient_credits`	`This needs 118,420 credits`
403	`phone_unverified`	`Verify your phone number to start creating.`

Credits

max(1, ceil(spoken characters × rate)), with 1 credit per character for speech and 2 for speech-hd. Charged in full when the audiobook starts and not adjusted afterwards. Refunded in full if the audiobook fails (after 4 failed attempts in a row).

Example

bash

curl -X POST https://api.cinara.ai/v1/studio/audiobooks \
  -H "Authorization: Bearer $CINARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Lighthouse Keeper",
    "author": "R. Ellison",
    "voiceId": "hearth",
    "language": "English",
    "chapters": [
      {"title": "The Harbour", "paragraphs": ["The fog came in before the boats did.", "Nobody in the village remembered a summer like it."]},
      {"title": "The Storm", "paragraphs": ["By midnight the wind had found every loose shutter on the hill."]}
    ]
  }'

Get an audiobook

GET /v1/studio/audiobooks/{id}

Reads an audiobook, records the next parts, and returns it with every finished chapter. Keep polling until status isn't running.

Response

200 OK

json

{
  "generation": {
    "id": "e9c3a7f1-4d8b-4b2e-a5c6-7f0d3b9e1a84",
    "module": "studio",
    "status": "running",
    "input": { "title": "The Lighthouse Keeper", "voiceId": "hearth", "voiceName": "Hearth · Margaret", "characters": 118420, "…": "…" },
    "output": {
      "phase": "speak",
      "stage": "processing",
      "stageLabel": "Recording chapter 2 of 12",
      "chapters": [
        {
          "title": "The Harbour",
          "characters": 9812,
          "parts": 3,
          "doneParts": [0, 1, 2],
          "size": 11203584,
          "seconds": 700.2
        },
        { "title": "The Storm", "characters": 10240, "parts": 3, "doneParts": [0] }
      ],
      "partsTotal": 34,
      "partsDone": 4
    },
    "credits": 118420,
    "error": null,
    "created_at": "2026-09-15T21:30:12.445019+00:00",
    "completed_at": null
  },
  "files": [
    {
      "name": "chapter-1",
      "label": "1. The Harbour",
      "contentType": "audio/mpeg",
      "size": 11203584,
      "url": "https://api.cinara.ai/media/1789552290/Rt5xE…/workspaces/…/studio/…/chapter-001.mp3"
    }
  ]
}

Field	Description
`output.partsDone` / `partsTotal`	Overall progress.
`output.chapters[].seconds`	A finished chapter's length.
`output.seconds`	Once finished: the whole book's length.
`files`	Every finished chapter, named `chapter-<n>` and labelled `<n>. <title>`, even while the rest records. Empty if the audiobook failed.

A finished audiobook has phase: "done" and stageLabel: "Done". A failed one has error: "Audiobook failed."

Errors

Status	`error`	Message
404	`not_found`	`Not found`

Credits

Free to read.

Polling example

bash

while :; do
  RES=$(curl -s "https://api.cinara.ai/v1/studio/audiobooks/$ID" -H "Authorization: Bearer $CINARA_API_KEY")
  STATUS=$(echo "$RES" | jq -r .generation.status)
  [ "$STATUS" != "running" ] && break
  echo "$(echo "$RES" | jq -r '"\(.generation.output.partsDone) of \(.generation.output.partsTotal) parts"')"
  sleep 3
done
echo "$RES" | jq -r '.files[] | "\(.name) \(.url)"'

Download a chapter

GET /v1/studio/audiobooks/{id}/files/{name}

Downloads one chapter (chapter-1, chapter-2, …) as an attachment.

A chapter can be downloaded as soon as it's finished, while the rest of the book is still recording.

Response

200 OK with the MP3 and Content-Disposition: attachment; filename="the-lighthouse-keeper-chapter-1.mp3".

Errors

Status	`error`	Message
404	`not_found`	`Chapter not ready`

Credits

Free.

Example

bash

curl -L "https://api.cinara.ai/v1/studio/audiobooks/e9c3a7f1-4d8b-4b2e-a5c6-7f0d3b9e1a84/files/chapter-1" \
  -H "Authorization: Bearer $CINARA_API_KEY" -o chapter-01.mp3

Studio ​

Get studio options ​

Response ​

Credits ​

Example ​

Create an audiobook ​

Request body ​

Response ​

Errors ​

Credits ​

Example ​

Get an audiobook ​

Response ​

Errors ​

Credits ​

Polling example ​

Download a chapter ​

Response ​

Errors ​

Credits ​

Example ​

Studio

Get studio options

Response

Credits

Example

Create an audiobook

Request body

Response

Errors

Credits

Example

Get an audiobook

Response

Errors

Credits

Polling example

Download a chapter

Response

Errors

Credits

Example