--- title: "Measure against a named profile and get back only the lenses that question needs" method: POST path: "/v1/analyze/profile" tags: ["Analyze"] --- # Measure against a named profile and get back only the lenses that question needs `POST /v1/analyze/profile` ## Request - Base URL: `https://audiolab.tools` - URL: `https://audiolab.tools/v1/analyze/profile` - Auth: HTTP bearer One preset answers one question, keyed by stable lens id. Profiles: basic, voice, master, provenance, dataset, environment, broadcast, loop, room, chain, pitch. Only basic is free, the rest return 402. series:true adds curves and can reach ~2 MB: for your own code, not for a chat client. ## Request body - object - `url` string, uri: Public http(s) URL to the audio file. - `objectPath` string: Path returned by /api/upload-url, for audio that has no public URL. Readable only by the key that uploaded it, and kept for about an hour so a follow-up question about the same file does not need a re-upload. - `profile` 'basic' | 'voice' | 'master' | 'provenance' | 'dataset' | 'environment' | 'broadcast' | 'loop' | 'room' | 'chain' | 'pitch', required: The preset. room: the reverberation time per octave band from one clap, balloon pop, impulse response or sweep (see roomSource); a recording that holds none of them is a 422 with the code room_not_measurable. chain: the gaps of digital silence inside the sound (lost packets). pitch: the pitch of a voice, how voiced the recording is and the harmonics-to-noise ratio. A measure that has not met its test yet (a beta that is not offered) is left out of the answer; the status of every measure is at https://audiolab.tools/lenses. - `series` boolean: Include per-block lanes and curves alongside the single values. - `round` boolean: Round the numbers to what the measurement is worth: dB and LUFS to 2 decimals, seconds to 3, shares to 3, Hz to 1. Same keys, same types, only fewer decimals. Off by default: without it you get the full precision, exactly as before. Supported on mixlab/analyze, voicelab/qa, signallab and analyze/profile. - `measureStatus` boolean: Add one extra key, measureStatus, with the status (validated, proxy, beta, withdrawn, planned), the basis, how it works (dsp, model, mixed) and, where known, the margin of every measure in the answer. Off by default: without it the answer has no extra key. Supported on mixlab/analyze, voicelab/qa, signallab and analyze/profile. - `contentModel` 'v1' | 'v2': Which model gives the content type (voice, music, mixed, noise, unknown) and its confidence. v1 is the first model and is the default until 15 January 2027; v2 is the new one, much better on speech and music in the tests (see the status of signal.contentType at https://audiolab.tools/lenses). The same keys and types in both, only the values differ, and with v2 the evidence list contains model:v2. From 15 January 2027 the default becomes v2 and v1 stays selectable until at least 15 April 2027. Supported on signallab and analyze/profile. - `roomSource` 'clap' | 'balloon' | 'impulse' | 'sweep': For the room profile: how the recording was made. clap: one clap (the default; the bands from 500 Hz up); balloon: one balloon pop (the same bands); impulse: the file already is an impulse response (every octave band from 125 Hz); sweep: the file holds the exponential sweep of the engine as the room returned it (every octave band from 125 Hz). Supported on analyze/profile with the room profile. - `speechDetector` 'v1' | 'k2': Which speech detector finds the speech in the recording; it decides speechRatio, speechSec, silenceSec, longSilences, segments and the measures that read the pauses. v1 is the first detector and is the default until 15 January 2027; k2 lets a phrase run on into its soft word starts and endings (by at most 100 ms per side) and was better on new speakers in the tests (frame F1 from 0.88 to 0.94 on clean audio and noise at 20 and 10 dB; see the status of voice.speechRatio at https://audiolab.tools/lenses). The same keys and types in both, only the values differ: with k2 the speech ratio reads about 5 to 14 points higher, everything that reads the speech frames or the pauses moves with it, signalToNoiseDb is corrected below 16 dB and reads about 4 to 5 dB lower at 10 dB noise and below (closer to the true ratio), and a pause measure is null when no pause frame is left; brightness, sibilanceRisk, noiseFloorDb and peakDb do not move (details: https://audiolab.tools/docs/start/changes-and-deprecation). From 15 January 2027 the default becomes k2 and v1 stays selectable until at least 15 April 2027. Supported on voicelab/qa, voicelab/segments and analyze/profile. ## Response `200` Measurement complete. - object - `profile` string - `measureStatus` MeasureStatus: Present only when the request asked for it with "measureStatus": true. For every measure in the answer that comes from a lens: how far to trust it. Keys are the field names of the answer (or the lens ids, for analyze/profile). Fields that are not measures (counts, flags, timings) have no entry. - `legend` string, uri: Where the five statuses are explained, and what you may and may not conclude from each. - `measures` object - `lenses` object: Measurements keyed by stable lens id, for example loudness.integrated or stereo.correlation. Values are computed over the whole file; with series:true the curves are capped at 2000 points and the per-event lists at 500, which shortens what is sent and never changes a measurement. - `totalSegments` integer: Speech segments found, before any cap. - `returnedSegments` integer: Segments in this response. Lower than totalSegments when truncated. - `totalRegions` integer: Timeline regions found, before any cap. - `returnedRegions` integer: Regions in this response. Lower than totalRegions when truncated. - `truncated` boolean: True when segments or regions were capped at 500, keeping the longest. Everything that runs per event is cut with them, so a value never lands on the wrong segment. - `outOfDomain` object: Present when the material is not speech but voice lenses were measured anyway. On music, music with vocals, noise or near-silence the speech-to-noise figures compare the vocal with everything around it, not speech with noise, so they are not a verdict on speech quality. The numbers stay; this says how to read them. - `reason` string - `contentType` 'music' | 'mixed' | 'noise' | 'silence' - `lenses` string[]: The lens ids this applies to. ## Other responses - `400`: Malformed request, a URL we could not use, or a parameter that is not valid. Codes: url_not_allowed, url_fetch_failed, invalid_json, missing_input, invalid_parameter, batch_too_large, upload_not_found. - `401`: Invalid or revoked API key. /v1/batch and /v1/usage always need a key; the analysis routes also run without one, as a small keyless trial. Codes: invalid_api_key. - `402`: A limit of your plan was reached: the calls or the data of the month, or a preset that needs a paid plan. The body carries usage where it applies. Codes: quota_exceeded, data_quota_exceeded, profile_requires_paid_plan, voice_minutes_exhausted. - `413`: File too large for the route, or a recording too long to decode. Codes: file_too_large, track_too_long. - `422`: File could not be decoded as audio. Codes: unsupported_format, room_not_measurable. - `429`: Too many requests this minute. See Retry-After. Codes: rate_limited. - `500`: Something went wrong on our side. The details are logged and never sent to you. Codes: storage_unavailable, analysis_error. --- [API](https://skmtc.dev/audiolab/apis/audiolab-api.md) · [All operations](https://skmtc.dev/audiolab/apis/audiolab-api/llms.txt) · [OpenAPI document](https://skmtc.dev/audiolab/apis/audiolab-api/revisions/69ff81f4f4ba?raw)