API reference

Media links

1 operation. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

POST/v1/media/refresh-url

Get a fresh link for a media file

Free and paid accounts

API key required
Free and paid accounts
No token cost

Media links that Scarleta returns can carry a signature that expires. Send a link you hold (url, an absolute address of at most 2048 characters, expired or not) and the route returns a freshly signed link for the same file, so a player can carry on. Only a file of your own account on Scarleta is signed. For anything else the answer is still 200 with url set to null: another account's file, an address on another site, or a link that cannot be signed right now. A null url means "no fresh link"; the link you already hold is not echoed back.

A missing, empty, over-long or relative url, and a body that is not valid JSON, are all 400 invalid_url. On success this route answers { data } without meta.

Cost. Free of charge.

curl -X POST "https://api.scarleta.ai/v1/media/refresh-url" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.scarleta.ai/v1/audio/media/9b2c7d1e-5a40-4f83-b6c9-0d1e2f3a4b5c.wav"
  }'

Request body

Name	Type	Required	Description
urlbody	string	Required	The link to refresh, an absolute address of at most 2048 characters. Allowed: 1 to 2048 characters.

Response fields

Field	Type	Description
url	string \| null	The freshly signed link, or null when the link is not a file of yours that can be signed.

Errors

Status	Code	Description
400	invalid_url	The body is not valid JSON, or `url` is missing, empty, too long or not an absolute address.
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "data": {
    "url": "https://api.scarleta.ai/v1/audio/media/9b2c7d1e-5a40-4f83-b6c9-0d1e2f3a4b5c.wav?exp=1791337470&sig=example-signature"
  }
}

200 A fresh link, or `url: null`.
400 The body is not valid JSON, or `url` is missing, empty, too long or not an absolute address.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget or the per-minute cap of this route. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, rate_limit_unavailable, unauthorized.