Generate and modify sheet music programmatically with a simple REST API.
The API is in beta. Limits and pricing may change as we gather usage data.
The YapScore API is a REST interface that accepts JSON and returns JSON (or SVG for the render endpoint). All endpoints live under .
https://yapscore.ai/api/v1/POST /v1/generateCreate a score from a prompt
POST /v1/modifyEdit a score with instructions
POST /v1/renderRender MusicXML to SVG
| Requirement | Value |
|---|---|
| Plan required | Pro only |
| Daily call limit | 20 calls / day (resets midnight UTC) |
Pass your API key in the Authorization header as a Bearer token. Keys start with ys_. You can create and revoke keys in your Settings page.
Authorization: Bearer ys_<your-api-key>
Keep your API key secret. Do not expose it in client-side code or public repositories. If a key is compromised, revoke it from Settings immediately.
/api/v1/generateGenerate a new score from a plain-language prompt. Returns a MusicXML string and an optional message from the AI.
Request
curl -X POST https://yapscore.ai/api/v1/generate \
-H "Authorization: Bearer ys_..." \
-H "Content-Type: application/json" \
-d '{"prompt": "A 4-bar waltz in D minor for piano"}'Response
{
"musicxml": "<?xml version=\"1.0\" ...>",
"message": "Here is a 4-bar waltz in D minor."
}Parameters
| Name | Type | Description |
|---|---|---|
| prompt | string | Required. Natural language description of the score to create. |
/api/v1/modifyEdit an existing score with a natural language instruction. Returns the modified MusicXML.
Request
curl -X POST https://yapscore.ai/api/v1/modify \
-H "Authorization: Bearer ys_..." \
-H "Content-Type: application/json" \
-d '{
"musicxml": "<?xml version=\"1.0\" ...>",
"prompt": "Transpose up a fifth and add a forte marking at measure 1"
}'Response
{
"musicxml": "<?xml version=\"1.0\" ...>"
}Parameters
| Name | Type | Description |
|---|---|---|
| musicxml | string | Required. The MusicXML string to modify. |
| prompt | string | Required. Natural language edit instruction. |
/api/v1/renderRender a MusicXML score to SVG. Returns image/svg+xml directly — not JSON.
Request
# Save SVG to file
curl -X POST https://yapscore.ai/api/v1/render \
-H "Authorization: Bearer ys_..." \
-H "Content-Type: application/json" \
-d '{"musicxml": "<?xml version=\"1.0\" ...>", "page": 1}' \
-o score.svgResponse
<!-- Returns SVG directly, Content-Type: image/svg+xml --> <svg xmlns="http://www.w3.org/2000/svg" ...> ... </svg>
Parameters
| Name | Type | Description |
|---|---|---|
| musicxml | string | Required. The MusicXML string to render. |
| page | number | Optional. Page number to render (default: 1). |
All error responses return JSON with an error field.
| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameters. |
| 401 | Unauthorized — API key missing, invalid, or revoked. |
| 403 | Forbidden — API access requires a Pro subscription. |
| 429 | Daily limit reached (20 calls/day). Resets at midnight UTC. Response includes { "error": "Daily API limit reached", "limit": 20, "resets": "midnight UTC" }. |
| 500 | Internal server error — try again later. |
Need higher limits, a dedicated integration, or a custom deployment? We're happy to work something out.
Talk to us
Higher daily limits · Custom pricing · Private deployments · SLA support
A minimal end-to-end example: generate a score, modify it, and render it to SVG.
const BASE = "https://yapscore.ai/api/v1";
const KEY = "ys_..."; // from Settings → API Keys
const headers = {
"Authorization": `Bearer ${KEY}`,
"Content-Type": "application/json",
};
// 1. Generate
const gen = await fetch(`${BASE}/generate`, {
method: "POST",
headers,
body: JSON.stringify({ prompt: "A 4-bar waltz in D minor" }),
});
const { musicxml } = await gen.json();
// 2. Modify
const mod = await fetch(`${BASE}/modify`, {
method: "POST",
headers,
body: JSON.stringify({ musicxml, prompt: "Add a forte at measure 1" }),
});
const { musicxml: modified } = await mod.json();
// 3. Render → SVG
const render = await fetch(`${BASE}/render`, {
method: "POST",
headers,
body: JSON.stringify({ musicxml: modified, page: 1 }),
});
const svg = await render.text(); // <svg ...>...</svg>