Game music | Sprite Flow Docs

What you can create

Generate music for exploration, combat, menus or cinematics. Lyria supports a requested duration and optional BPM; Suno uses its own generation controls. Example: create a 60-second instrumental forest exploration cue.

Prepare the music brief

Describe mood, instruments, energy and intended use in prompt. Choose engine: lyria or suno. Instrumental defaults to true. When instrumental is false, supply at least three characters of lyrics. No input image or audio upload is required for this text-to-music workflow.

Generate music in the workspace

Open Game music generator.
Choose the engine and describe the cue. Enter lyrics for a song.
For Lyria, set the duration and optional tempo.
Select a destination, review the cost and generate.
Listen to all returned tracks and download the available audio formats.

Choices, limits and cost

A generation costs 4 credits. Lyria allows 1–240 seconds, defaulting to 60; Suno does not accept a user-controlled duration in this contract. Prompt length is 3–800 characters, lyrics up to 5,000. Lyria titles allow 120 characters; Suno titles allow 80. A result can contain multiple tracks; use task asset IDs instead of assuming one audio file.

Parameters

These fields are generated from the same input Schema used by REST and MCP. Nested required fields apply when their parent object or selected variant is present. Business conditions described above are validated before submission.

Field	Type	Required	Default and limits
`characterId`	string	No	minLength: 1; maxLength: 255
`characterTarget`	object / object	No	See the workflow requirements above.
`projectId`	string	No	minLength: 1; maxLength: 255
`folderId`	string / null	No	See the workflow requirements above.
`title`	string	No	Default: `""`; maxLength: 120
`prompt`	string	Yes	minLength: 3; maxLength: 800
`instrumental`	boolean	No	Default: `true`
`lyrics`	string	No	Default: `""`; maxLength: 5000
`engine`	string	Yes	Must be `"lyria"`
`durationSeconds`	integer	No	Default: `60`; minimum: 1; maximum: 240
`bpm`	integer	No	minimum: 1; maximum: 9007199254740991
`engine`	string	Yes	Must be `"suno"`
`title`	string	No	Default: `""`; maxLength: 80

API example

This example costs 4 credits. A quote does not reserve balance or bypass subscription requirements. Set SPRITEFLOW_API_KEY in your shell. Replace the placeholder asset ID 00000000-0000-4000-8000-000000000001 with a ready asset you own when present. Use a new idempotency key for each intentional generation; keep it unchanged when retrying.

bash

1
2# Use the same BASE_URL for credentials, uploads and generation.
3BASE_URL="https://spriteflow.io"
4IDEMPOTENCY_KEY="example-workflow-001"
5
6cat > request.json <<'JSON'
7{
8  "operation": "generate_music",
9  "input": {
10    "engine": "lyria",
11    "prompt": "Quiet forest exploration, acoustic guitar and soft strings",
12    "durationSeconds": 60,
13    "instrumental": true
14  }
15}
16JSON
17
18curl --fail-with-body "$BASE_URL/api/v1/estimates" \
19  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
20  -H "Content-Type: application/json" --data-binary @request.json
21
22curl --fail-with-body "$BASE_URL/api/v1/tasks" \
23  -H "Authorization: Bearer $SPRITEFLOW_API_KEY" \
24  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
25  -H "Content-Type: application/json" --data-binary @request.json
26

An accepted request returns HTTP 202, Location and Retry-After headers. Example response (IDs are illustrative):

json

1{"taskId":"00000000-0000-4000-8000-000000000002","status":"accepted","statusUrl":"/api/v1/tasks/00000000-0000-4000-8000-000000000002","pollAfterSeconds":10,"replayed":false}

MCP example

Call estimate_cost with the same operation and input, then call generate_music. The following is a tools/call params object:

json

1{
2  "name": "generate_music",
3  "arguments": {
4    "input": {
5      "engine": "lyria",
6      "prompt": "Quiet forest exploration, acoustic guitar and soft strings",
7      "durationSeconds": 60,
8      "instrumental": true
9    },
10    "idempotencyKey": "example-workflow-001"
11  }
12}

The tool returns the same task receipt in structuredContent and a JSON text result. Pass taskId to get_task. Tool annotations describe behavior; permissions are still checked on the server.

Completion, download and reuse

Poll the returned statusUrl after pollAfterSeconds. Continue while terminal is false. Read items for per-task results, progress for batch counts and assets for ready files. A batch can be partially_completed: use its successful assets and review each failed item before deciding whether to create a separate retry.

For each returned asset ID, call get_download_url or GET /api/v1/assets/{assetId}/download. Download the temporary URL before it expires. Image assets can be passed into a compatible operation as inputAssetId or a style reference. Do not pass provider task IDs, download URLs or local filesystem paths as asset IDs.

Failures and recovery

INVALID_PARAMETERS: fix the field errors before submitting. Check the business conditions and defaults above.
INPUT_ASSET_UNAVAILABLE: confirm the upload, check ownership and ensure the asset is ready and not trashed.
INSUFFICIENT_CREDITS: add credits before a new request; a cost estimate does not reserve them.
A timeout or lost response: resend the identical request with the original idempotency key. Never invent a new key just because the response was lost.
A terminal generation failure: inspect the item error and refund information. Refund handling uses the existing generation workflow. Do not assume an in-progress or unknown submission is safe to repeat.

Uploads · Tasks · Credits · Idempotency · Save destinations · Download and export