Gravity Feed quickstart

Create a key, send a first plan request with curl and read the alternatives safely.

This quickstart takes you from no account to a real Gravity Feed plan in a few minutes. You will try the playground, create a key, send a request with curl and read the result. Nothing here uploads audio.

1. Try the playground

Open the Gravity Feed page. Signed out, the playground shows a labeled sample plan built by the real compiler from hand-written choices. Signed in, the same playground sends a live request for a six-track chorus and counts against your limit.

2. Create a key

  1. Sign in and open the Gravity Feed console.
  2. Choose Create key, give it a name such as REAPER studio, and copy the secret. It starts with s9gf_ and is shown only once.
  3. Store it in your DAW script, plugin settings or a secret manager. Never commit it to a repository.

You can hold up to 10 active keys. Revoking a key takes effect on the next request.

3. Check the service

curl -s https://spatial9.ai/api/gravity-feed/v1/capabilities

The answer lists the schema version, limits, styles, motion shapes, effect kinds and the transports. GET /v1/profiles lists the Gravity Profiles your adapter can target.

4. Send a plan request

curl -X POST https://spatial9.ai/api/gravity-feed/v1/plans \
  -H "X-API-Key: s9gf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.0",
    "request_id": "chorus-take-1",
    "session": {
      "id": "song-42", "revision": 7,
      "tempo_map": [{ "beat": 0, "bpm": 120 }],
      "selection": { "start_beat": 64, "length_beats": 32 },
      "sections": [{ "label": "Chorus", "start_beat": 64, "end_beat": 96 }]
    },
    "intent": "Open the chorus upward without moving the vocal",
    "tracks": [
      { "id": "vox", "role": { "value": "lead_vocal", "source": "user" }, "anchor": true },
      { "id": "pad", "role": { "value": "pad", "source": "host" }, "target_id": "enc-1" }
    ],
    "targets": [
      { "id": "enc-1", "profile_id": "iem_stereoencoder_candidate_v1", "live_write": true, "automation_commit": true }
    ],
    "privacy": { "mode": "metadata_only", "audio_uploaded": false }
  }'

5. Read the plan

The response has three alternatives: restrained, expressive and cinematic. In each one:

FieldUse it to
summaryShow the idea in one line
sceneDraw each track's position and whether it changed
motionsAnimate or preview the movement
effect_suggestionsShow effect ideas to apply by hand
actionsWrite automation to a bound plugin
unsupported_actionsTell the user what could not be applied and why

Before writing, compare preconditions.session_revision with your current revision and check expires_at. If either fails, request a new plan.

6. Retry safely

If the network drops, send the same body with the same request_id. You get the stored plan back with the Idempotent-Replayed: true header and it does not count again. Reusing a request_id with a different body returns 409 idempotency_conflict.

Next steps

Go deeper on the blog