StudioSphere Pulse — Audio Intelligence

Start a temporary, email-free Pulse trial. Returns a short-lived private API key with enough banked tokens for one short URL-based v1 analysis. No Stripe Checkout session is created. Store the key in the client or a trusted local environment; do not repost it in public logs, screenshots, GitHub issues, shared chats, or directory examples.

{
  "type": "object",
  "properties": {},
  "required": []
}

{
  "type": "object",
  "properties": {
    "api_key": {
      "type": "string",
      "description": "Temporary Pulse API key for the trial account. Treat as private; do not print it in public logs, screenshots, GitHub issues, shared chats, or directory examples."
    },
    "account_type": {
      "type": "string",
      "enum": [
        "trial"
      ],
      "description": "The account type created by this tool."
    },
    "banked_tokens": {
      "type": "number",
      "description": "Trial token balance granted."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO timestamp when the temporary key expires."
    },
    "usage_note": {
      "type": "string",
      "description": "Limits and usage guidance for the trial."
    },
    "analyze_path": {
      "type": "string",
      "description": "REST path for authenticated analysis."
    },
    "estimate_path": {
      "type": "string",
      "description": "REST path for free estimates."
    },
    "upgrade_path": {
      "type": "string",
      "description": "Path for converting to an account."
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "api_key",
        "account_type",
        "banked_tokens",
        "expires_at",
        "usage_note"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

Get the exact price to analyze an audio file before committing. Always call this first. Returns cost in dollars and a job_estimate_id valid for 30 minutes. Free — never charged.

{
  "type": "object",
  "properties": {
    "audio_url": {
      "type": "string",
      "description": "Publicly accessible URL of the audio file (MP3, WAV, FLAC, OGG, Opus)."
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "bpm",
          "key",
          "waveform"
        ]
      },
      "description": "Analysis tools to price. Available in v1.0: bpm, key, waveform. Coming soon: structure, chords."
    }
  },
  "required": [
    "audio_url",
    "tools"
  ]
}

{
  "type": "object",
  "properties": {
    "cost_usd": {
      "type": "number",
      "description": "Estimated analysis cost in USD."
    },
    "cost_display": {
      "type": "string",
      "description": "Human-readable USD estimate."
    },
    "tokens": {
      "type": "number",
      "description": "Estimated Pulse tokens."
    },
    "breakdown": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "tokens": {
            "type": "number"
          },
          "cost_usd": {
            "type": "number"
          }
        },
        "required": [
          "tokens",
          "cost_usd"
        ],
        "additionalProperties": true
      },
      "description": "Per-tool token and cost estimate."
    },
    "duration_estimate_sec": {
      "type": "number",
      "description": "Estimated audio duration in seconds."
    },
    "job_estimate_id": {
      "type": "string",
      "description": "Estimate identifier valid for the configured TTL."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO timestamp when the estimate expires."
    },
    "content_type": {
      "type": "string"
    },
    "content_length_bytes": {
      "type": "number"
    },
    "duration_inferred": {
      "type": "boolean"
    },
    "audio_url_normalized": {
      "type": "string"
    },
    "audio_url_original": {
      "type": "string"
    },
    "normalize_source": {
      "type": "string"
    },
    "note": {
      "type": "string"
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "cost_usd",
        "cost_display",
        "tokens",
        "breakdown",
        "duration_estimate_sec",
        "job_estimate_id",
        "expires_at"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

Run audio analysis on a public audio URL. Requires estimate_cost to be called first (job_estimate_id). Requires PULSE_API_KEY. Before calling, you MUST confirm with the user that they have a lawful basis to submit this audio for analysis. For a user-requested folder, project, playlist, or batch, one confirmation can cover every track in that scope. Returns job_id — poll get_job_status for results.

{
  "type": "object",
  "properties": {
    "audio_url": {
      "type": "string",
      "description": "Public URL of the audio file."
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "bpm",
          "key",
          "waveform"
        ]
      },
      "description": "Analysis tools to run. Available in v1.0: bpm, key, waveform. Coming soon: structure, chords."
    },
    "job_estimate_id": {
      "type": "string",
      "description": "The job_estimate_id returned by estimate_cost. Must not be expired (30 min TTL)."
    },
    "attestation_confirmed": {
      "type": "boolean",
      "description": "Set to true ONLY after the user has confirmed they have rights, permission, lawful access, or another legal basis to submit this audio, or the current user-requested batch/folder/project containing it, for analysis."
    }
  },
  "required": [
    "audio_url",
    "tools",
    "job_estimate_id",
    "attestation_confirmed"
  ]
}

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "True when analysis was accepted."
    },
    "job_id": {
      "type": "string",
      "description": "Pulse analysis job id."
    },
    "status": {
      "type": "string",
      "description": "Current job status."
    },
    "cache_hits": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tools served from cache."
    },
    "tokens_estimated": {
      "type": "number",
      "description": "Estimated token charge."
    },
    "cost_usd_estimated": {
      "type": "number",
      "description": "Estimated USD value."
    },
    "poll_url": {
      "type": "string",
      "description": "Relative status polling URL."
    },
    "stream_url": {
      "type": "string",
      "description": "Relative SSE status URL."
    },
    "account_type": {
      "type": "string",
      "description": "Account type used for the request."
    },
    "upgrade_path": {
      "type": "string"
    },
    "conversion_note": {
      "type": "string"
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "ok",
        "job_id",
        "status",
        "cache_hits",
        "tokens_estimated",
        "cost_usd_estimated",
        "poll_url",
        "stream_url"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

Generate a one-time Stripe payment page for users without a Pulse account. Before calling, you MUST confirm with the user that they have a lawful basis to submit this audio for analysis; for a user-requested batch/folder/project, one confirmation can cover that scope. Present the payment_url to the user as a link. Analysis begins automatically after payment. Poll get_job_status with the returned job_id.

{
  "type": "object",
  "properties": {
    "job_estimate_id": {
      "type": "string",
      "description": "The job_estimate_id returned by estimate_cost."
    },
    "attestation_confirmed": {
      "type": "boolean",
      "description": "Set to true ONLY after the user has confirmed they have rights, permission, lawful access, or another legal basis to submit this audio, or the current user-requested batch/folder/project containing it, for analysis."
    }
  },
  "required": [
    "job_estimate_id",
    "attestation_confirmed"
  ]
}

{
  "type": "object",
  "properties": {
    "payment_url": {
      "type": "string",
      "description": "Stripe Checkout URL to present to the user."
    },
    "job_id": {
      "type": "string",
      "description": "Pulse job id for polling after payment."
    },
    "cost_display": {
      "type": "string",
      "description": "Human-readable estimated cost."
    },
    "charged_display": {
      "type": "string",
      "description": "Human-readable upfront Checkout charge."
    },
    "amount_charged_cents": {
      "type": "number",
      "description": "Stripe Checkout charge in cents."
    },
    "amount_estimate_cents": {
      "type": "number",
      "description": "Estimated usage value in cents."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO timestamp when the Checkout link expires."
    },
    "deduped": {
      "type": "boolean",
      "description": "True when an existing active Checkout link was reused."
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "payment_url",
        "job_id",
        "cost_display",
        "charged_display",
        "amount_charged_cents",
        "amount_estimate_cents",
        "expires_at"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

Check the status and results of an analysis job. Poll after analyze_track returns job_id, or after the user pays via request_payment_link. Returns full results when status=completed.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job_id returned by analyze_track or request_payment_link."
    },
    "include_waveform_data": {
      "type": "boolean",
      "description": "Optional. Defaults to false so chat agents receive a compact waveform summary plus result_url. Set true only if raw waveform samples are needed."
    },
    "include_waveform_image": {
      "type": "boolean",
      "description": "Optional. Defaults to true. When the job has waveform data, include a server-rendered SVG as MCP image content so the client can display it without fetching a URL."
    }
  },
  "required": [
    "job_id"
  ]
}

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Pulse analysis job id."
    },
    "status": {
      "type": "string",
      "description": "Current or terminal job status."
    },
    "result_url": {
      "type": "string",
      "description": "Public result page URL."
    },
    "results": {
      "type": "object",
      "additionalProperties": true,
      "description": "Analysis results when available."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Analysis metadata, including asset type, source hints, library metadata, and confidence policy when available."
    },
    "result_provenance": {
      "type": "object",
      "additionalProperties": true,
      "description": "Per-tool provenance and applicability summary for interpreting detected, filename-sourced, suppressed, or low-confidence results."
    },
    "result_quality_notes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Human-readable quality notes for suppressed, low-confidence, filename-sourced, or review-needed results."
    },
    "tokens_estimated": {
      "type": "number"
    },
    "tokens_charged": {
      "type": "number"
    },
    "cost_usd": {
      "type": "number"
    },
    "expires_at": {
      "type": "string"
    },
    "completed_at": {
      "type": "string"
    },
    "payment_source": {
      "type": "string"
    },
    "billing": {
      "type": "object",
      "additionalProperties": true
    },
    "waveform_svg_url": {
      "type": "string"
    },
    "waveform_png_url": {
      "type": "string"
    },
    "waveform_markdown": {
      "type": "string"
    },
    "waveform_image": {
      "type": "object",
      "additionalProperties": true
    },
    "waveform_file": {
      "type": "object",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "job_id",
        "status"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

Check the banked token balance for the authenticated Pulse account. Requires PULSE_API_KEY.

{
  "type": "object",
  "properties": {},
  "required": []
}

{
  "type": "object",
  "properties": {
    "banked_tokens": {
      "type": "number",
      "description": "Current banked-token balance."
    },
    "api_key_prefix": {
      "type": "string",
      "description": "Redacted API-key prefix."
    },
    "account_type": {
      "type": "string",
      "description": "Pulse account type."
    },
    "trial_expires_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Trial expiry timestamp if this is a trial account."
    },
    "account_created_at": {
      "type": "string",
      "description": "Account creation timestamp."
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "banked_tokens",
        "api_key_prefix",
        "account_type",
        "trial_expires_at",
        "account_created_at"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

List the available Pulse token packs (tier label, token count, price). Use before purchase_token_pack to show options to the user.

{
  "type": "object",
  "properties": {},
  "required": []
}

{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether token-pack purchasing is enabled."
    },
    "packs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "pack": {
            "type": "string"
          },
          "tokens": {
            "type": "number"
          },
          "amount_cents": {
            "type": "number"
          },
          "amount_usd": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "description": "Available token-pack tiers."
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "enabled",
        "packs"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}

Create a Stripe Checkout session for a Pulse token pack. Returns payment_url — DO NOT submit it programmatically; surface it to the user so they can complete payment in their browser. Once paid, banked tokens are credited automatically. Requires PULSE_API_KEY.

{
  "type": "object",
  "properties": {
    "pack": {
      "type": "string",
      "enum": [
        "10K",
        "50K",
        "200K"
      ],
      "description": "Token pack tier"
    }
  },
  "required": [
    "pack"
  ]
}

{
  "type": "object",
  "properties": {
    "purchase_id": {
      "type": "string",
      "description": "Pulse token-pack purchase id."
    },
    "pack": {
      "type": "string",
      "description": "Token-pack tier label."
    },
    "tokens": {
      "type": "number",
      "description": "Tokens included in the pack."
    },
    "amount_usd": {
      "type": "number",
      "description": "Pack price in USD."
    },
    "currency": {
      "type": "string",
      "description": "Checkout currency."
    },
    "payment_url": {
      "type": "string",
      "description": "Stripe Checkout URL to present to the user."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO timestamp when the Checkout link expires."
    },
    "error": {
      "type": "string",
      "description": "Machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable recovery guidance."
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether the caller may retry after changing state or waiting."
    },
    "details": {
      "type": "object",
      "additionalProperties": true,
      "description": "Additional structured context from Pulse."
    }
  },
  "required": [],
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "purchase_id",
        "pack",
        "tokens",
        "amount_usd",
        "currency",
        "payment_url",
        "expires_at"
      ]
    },
    {
      "required": [
        "error",
        "message"
      ]
    }
  ]
}