Segue Developer API

Generate, search and stream AI-generated songs. Every request needs an API key from the API keys page.

Authorization: Bearer sgk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Search

GET /v1/tracks/search?q=wedding&language=ja&usage=wedding&limit=10

q is semantic when available, otherwise it matches titles and lyrics. Filters: genre, usage, scene, tags, language, vocal, bpm_min, bpm_max, kind, visibility. Page with next_cursor. Valid ids: GET /v1/catalog.

Track details and lyrics

GET /v1/tracks/{id}

Download

POST /v1/tracks/{id}/download-url   {"expires_in": 3600}
→ {"url": "https://api.segue.day/v1/files/…", "expires_at": "…"}

The URL needs no API key and expires (60 s – 24 h). Range requests are supported.

Generate (asynchronous)

POST /v1/generations
{
  "prompt": "walking home after the rain",
  "language": "ja",
  "genre": "city_pop",
  "vocal": true,
  "bpm": 96,
  "visibility": "private",
  "callback_url": "https://example.com/segue/webhook",
  "idempotency_key": "order-1234"
}
→ 202 {"id": "…", "status": "queued", …}

GET /v1/generations/{id}
→ {"status": "succeeded", "track": {…}, "download": {"url": "…", "expires_at": "…"}}

private songs are visible only to your API keys. public songs are also played in the Segue app. The default is set on the Settings page.

Callbacks

Create a signing secret on the Settings page. Each callback has Segue-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + rawBody). Return 2xx; failures are retried up to 5 times. Deduplicate with Segue-Event-Id.

import crypto from "node:crypto";
const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Errors and limits

Errors are {"error": {"code", "message"}} with an HTTP status. 60 requests per minute per account; generations are limited per day. 429 and 503 include Retry-After.

All songs are AI-generated. Show that they are AI-generated where you publish them.