Mesures

Une mesure traverse trois états — created, started, ended — et l’API vous laisse la mener soit en un appel, soit en deux.

Les routes

Les routes « créer et exécuter » sont celles vers lesquelles se tourner. La forme en deux temps existe pour les cas où il vous faut l’identifiant avant d’avoir le média — c’est ainsi que le widget s’en sert.

Décrire la personne

Plusieurs variables ne se calculent pas à partir du seul signal. userData est l’endroit où vous dites ce qu’il faut.

Tous les champs sont facultatifs. Ce que vous omettez ne fait que réduire ce qui peut être calculé :

Choisir les variables

Deux tableaux facultatifs réduisent ce qui est calculé :

{
  "desiredVariables": ["hr", "br"],
  "unwantedVariables": ["faceBmi"]
}

Omettez les deux et la mesure calcule tout ce à quoi votre compte a droit.

Envoyer une vidéo enregistrée

POST /measures/rppg/video
Authorization: Bearer <apiKey>
Content-Type: multipart/form-data

L’appel ci-dessous s’adresse à la Production. Envoyez-le au Test tant que vous validez encore une chaîne — les mesures qui y sont faites n’apparaissent jamais dans vos données de Production.

curl -sX POST https://api.saphere.ai/measures/rppg/video \
  -H "Authorization: Bearer $SAPHERE_API_KEY" \
  -F "video=@./capture.mp4;type=video/mp4" \
  -F "userData[sex]=F" \
  -F "userData[age]=35" \
  -F "userData[weight]=58" \
  -F "userData[height]=171" \
  -F "userData[smokingStatus]=non-smoker" \
  -F "tags=cohort-a,pilot"

La réponse est la mesure aboutie — la même forme que celle livrée par le widget.

Envoyer des images

POST /measures/rppg/images

Tout le reste est identique à la route vidéo.

Relire une mesure

GET /measures/{measureId}
Authorization: Bearer <apiKey>

Les mesures appartenant à un autre client rendent 404, en texte brut, exactement comme une mesure inexistante.

Supprimer une mesure

DELETE /measures/{measureId}
Authorization: Bearer <apiKey>

Cet appel retire les médias conservés — captures, images, vidéo, signaux — puis la ligne de la mesure. Il est rejouable sans risque : un objet absent n’est pas une erreur, de sorte qu’une suppression interrompue à mi-course se relance simplement.

Le résultat

{
  "id": "3f1a5c88-0b2d-4e6a-9c11-7d5e8a2b4f60",
  "status": "ended",
  "type": "rppg",
  "createdAt": "2026-08-24T14:57:44.000Z",
  "startedAt": "2026-08-24T14:57:46.000Z",
  "endedAt": "2026-08-24T14:58:22.000Z",
  "returnedVariables": ["hr", "br", "strs", "bp"],
  "signal": { "qualityScore": { "value": 100, "error": null } },
  "variables": {
    "hr":   { "value": { "mean": 72.4 }, "error": null },
    "br":   { "value": { "mean": 15.1 }, "error": null },
    "strs": { "value": { "level": 2, "scale": { "min": 1, "max": 5 } }, "error": null },
    "bp":   { "value": null, "error": "MISSING_USER_DATA_AGE" }
  },
  "userData": { "sex": "F", "weight": 58, "height": 171 },
  "tags": ["cohort-a"]
}

returnedVariables est un droit, non un résultat

C’est le champ le plus souvent mal lu. Il énumère les variables que votre compte client a le droit de recevoir, réduites par les desiredVariables / unwantedVariables que vous avez passés. Il n’énumère pas ce qui a réussi.

Formes des valeurs

Chaque variable est l’une de deux choses : une valeur avec error: null, ou value: null accompagné d’un code d’erreur.

Testez toujours error en premier :

const hr = result.variables.hr
if (hr?.error === null)
    console.log("heart rate:", hr.value.mean)
else if (hr)
    console.warn("heart rate unavailable:", hr.error)
else
    console.warn("heart rate not granted to this account")

L’indicateur de qualité

"signal": { "qualityScore": { "value": 100, "error": null } }

Pour juger si une mesure est exploitable, lisez les variables une à une et leurs codes d’erreur.

Construisez ce jugement sur des données de Test d’abord : les droits et le quota se règlent par compte, donc ce que rend un client de Test n’est pas nécessairement ce que rendra votre client de Production. Environnements expose la séparation.