API reference

Create lullaby

Generates a sung lullaby (audio) from a prompt. Costs 1 credit (2 with a cover image), charged on success only.

Request

POST/api/v1/lullaby

Requires Authorization: Bearer sk_live_.... Returns 202 Accepted with a job_id; poll GET /api/v1/jobs/{job_id} until the job reaches a terminal status.

POST /api/v1/lullaby

curl -X POST https://www.sleepytale.com/api/v1/lullaby \
  -H "Authorization: Bearer $SLEEPYTALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sleepy little fox curling up under the stars"}'

Headers

Parameter	Type	Description
`Authorization`required	string	Bearer token with your secret key: Bearer sk_live_...
`Idempotency-Key`optional	string	Optional unique key. Replaying the same key returns the same job instead of creating a new one.

Body

Parameter	Type	Description
`prompt`required	string	What the lullaby should be about. Max 2,000 characters.
`include_image`optional	boolean	When true, also generate a cover image (+1 credit). When false, audio only: faster and cheaper. Defaults to `false`.
`style`optional	string	Optional art style for the cover image (only used when include_image is true). Truncated to 60 characters.

Responses

Response by status

{
  "job_id": "1936f2b0a1c-7e1c2a3b-…",
  "status": "queued"
}

An idempotent replay returns the same job and may report its current status (processing / succeeded / failed) instead of queued. See the overview for the full error-code table and rate-limit headers.

Asynchronous by design

A 202 means the job is accepted, not finished. The audio arrives via GET /api/v1/jobs/{job_id} once status is succeeded.