Back to introduction

Quickstart

Get a key, submit audio, receive a webhook. Three steps from zero to your first result, no sales call needed.

1

Get an API key

Create an account and generate a key in seconds, self-serve, no waiting. The free tier comes with a one-time token grant so you can make real calls before you ever pay; upgrade to a paid plan whenever you're ready for production volume.

Keep the key server-side and send it as Authorization: Bearer <api_key> on every request.

2

Make your first call

Submit a batch of audio to a recipe. Pass a webhook_url so we can notify you the moment it finishes. A batch holds up to 500 audio URLs and needs a paid key. The call returns immediately with 202 Accepted and a batch_id . The work runs asynchronously.

curl -X POST https://api.scarleta.ai/v1/batch \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe_id": "your_recipe_id",
    "audio_urls": ["https://example.com/track.wav"],
    "webhook_url": "https://your-app.com/hooks/scarleta"
  }'
3

Receive the result

Completion webhookRecommended

Don't poll, we'll call you. When the batch finishes, Scarleta sends a POST to your webhook_url with a batch_completed event. Your endpoint acknowledges with a 2xx and reads the results. No loop, no wasted requests.

{
  "event": "batch_completed",
  "batch_id": "b1a2c3d4-…",
  "status": "completed",
  "total_items": 1,
  "completed_items": 1,
  "failed_items": 0,
  "cancelled_items": 0,
  "actual_total_cost": 12,
  "completed_at": 1786300927000
}
  • Delivered as soon as the batch reaches a terminal state.
  • Delivered in up to 3 attempts with backoff. The URL you pass with a request is sent once per completion; registered addresses get each event at least once, so de-duplicate on batch_id + completed_at (job_id for recipe runs).
  • Once notified, fetch per-item output from GET /v1/batch/{id}/results.
Read the webhooks reference
PollingFallback

If you can't receive an inbound webhook, for example from a local script or a short-lived job, poll the batch status instead. This is the alternative, not the default path: prefer the webhook whenever your app can accept one.

curl https://api.scarleta.ai/v1/batch/$BATCH_ID \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

# When status is "completed", fetch the per-item results:
curl "https://api.scarleta.ai/v1/batch/$BATCH_ID/results" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"

Next steps