API reference

Overview

Everything shared by the three endpoints: base URL, auth, errors, rate limits, and idempotency.

Base URL

All endpoints live under a single production base URL:

https://www.sleepytale.com/api/v1

Authentication

Authenticate every request with your secret key as a bearer token. The key is the identity. Requests never accept a user id. Create keys from your Dashboard.

Authorization: Bearer sk_live_...

Errors

Every error response uses the same envelope: an error object with a machine-readable code and a human-readable message.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry later."
  }
}

Code	Status	Meaning
`bad_request`	400	Malformed JSON, or a missing/oversized prompt.
`content_rejected`	400	The prompt failed the child-appropriateness content check.
`unauthorized`	401	Missing or invalid API key.
`insufficient_tokens`	402	Monthly credit allotment exhausted. Also appears as a job error if the balance ran out before work began.
`subscription_inactive`	402	The subscription is not active.
`not_found`	404	Job not found, or it belongs to a different account.
`rate_limited`	429	Too many requests. Retry after the Retry-After window.
`internal`	500	Unexpected server error.
`generation_failed`	job error	The generation failed. No credits are charged.
`busy`	job error	No processing slot became available (concurrency cap). Resubmit the job.

A failed job reports its reason in error.code on the job itself (generation_failed, insufficient_tokens, or busy). Failed jobs never consume credits.

Rate limits

Requests per minute and concurrent jobs are set by your plan (see Pricing). When you exceed the request limit the API returns 429 with these headers:

Retry-After: seconds to wait before retrying.
X-RateLimit-Remaining: requests left in the current window.

Idempotency

Both generation endpoints accept an optional Idempotency-Key header. Replaying a request with the same key returns the same job, including its current status, instead of creating and charging for a new one. Use a fresh unique key (a UUID works well) per logical generation, and reuse it on network retries.

Replay responses can skip 'queued'

A replayed request may report the job's current status (processing, succeeded, or failed) rather than queued.

Endpoints

`POST /api/v1/lullaby`	Create lullaby: sung audio, 1 credit.
`POST /api/v1/musical`	Create musical: narrated story with song, 2 credits.
`GET /api/v1/jobs/{job_id}`	Get job: poll status and fetch results.