Chat / Agent API

Drop a conversational audio agent into your own product. Describe what you want in plain language: the agent picks the right capabilities, runs them, and returns results. This is a live, metered developer surface, distinct from the consumer chat experience on scarleta.ai.

Accepts scar_live_* and sk_free_* keysMetered per use

Standard tier: async

Submit a turn with POST /v1/chat and poll GET /v1/chat/:job_id until it's done. Best for background work and server-to-server calls.

Streaming tier

Stream the response token-by-token with POST /api/chat. Best for interactive, in-product chat where you want output to appear as it's generated.

Submit a turn (standard tier)

POST/v1/chat

Submit a conversational turn asynchronously. Returns a job_id you poll for the result.

curl -X POST https://api.scarleta.ai/v1/chat \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "3f9a2b1c-7d4e-4a1b-9c8f-2e5d6a0b1f34",
    "message": "Remove the vocals from this track and tell me its key.",
    "audio_urls": ["https://example.com/song.wav"]
  }'

Parameters

Name	Type	Required	Description
message	string	Required	What you want, in plain language.
conversation_id	string	Optional	Thread turns together across calls. Omit to start a new conversation.
audio_urls	string[]	Optional	Audio the agent should work with for this turn.

Response

Field	Type	Description
job_id	string	Poll this with GET /v1/chat/:job_id.
status	string	IN_QUEUE on submit.
conversation_id	string	The thread this turn belongs to.

Example response

{
  "job_id": "job_7c1d2e",
  "status": "IN_QUEUE",
  "conversation_id": "3f9a2b1c-7d4e-4a1b-9c8f-2e5d6a0b1f34"
}

Poll for the result

GET/v1/chat/{job_id}

Fetch the status and, once complete, the assistant's reply for a submitted turn.

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

Response

Field	Type	Description
status	string	IN_QUEUE, or terminal completed / failed.
message	object	The assistant's reply once completed.
conversation_id	string	The thread this turn belongs to.

Example response

{
  "job_id": "job_7c1d2e",
  "status": "completed",
  "conversation_id": "3f9a2b1c-7d4e-4a1b-9c8f-2e5d6a0b1f34",
  "message": {
    "role": "assistant",
    "content": "Here's the instrumental. The track is in A minor at 96 BPM."
  }
}

Stream a turn (streaming tier)

POST/api/chat

The streaming variant of the same conversational surface: the response is streamed back as it is generated.

curl -N -X POST https://api.scarleta.ai/api/chat \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "3f9a2b1c-7d4e-4a1b-9c8f-2e5d6a0b1f34",
    "message": "Transcribe the vocals and align them to the beat."
  }'

Parameters

Name	Type	Required	Description
message	string	Required	What you want, in plain language.
conversation_id	string	Optional	Thread turns together across calls. Must be a UUID; omit to let the server generate one.

Next steps

MCP server Batch API Pricing