Les champs personnalisés

Les champs personnalisés sont ceux que votre organisation a ajoutés à sa bibliothèque : ce qu’un asset peut porter à côté de son titre et de sa description — un lien utile, un format, une date de tournage, un intervenant. Chaque organisation a les siens, et l’API les décrit avant de les écrire :

Les valeurs d’un asset se lisent dans le custom_fields de GET /v1/assets/{asset_id}.

Lister les champs

curl https://api.videas.com/v1/custom-fields \
  -H "Authorization: Bearer $VIDEAS_API_KEY"

{
  "data": [
    {
      "id": "0192a680-1d2e-7f3a-8b4c-5d6e7f8a9b0c",
      "label": "Lien utile",
      "slug": "lien-utile",
      "type": "link",
      "multiple": false,
      "required": false,
      "public": true,
      "workspace_id": null,
      "asset_types": null,
      "created_at": "2026-03-02T10:00:00Z",
      "updated_at": "2026-03-02T10:00:00Z"
    },
    {
      "id": "0192a680-2e3f-7a4b-9c5d-6e7f8a9b0c1d",
      "label": "Format",
      "slug": "format",
      "type": "choice",
      "multiple": false,
      "required": false,
      "public": true,
      "workspace_id": null,
      "asset_types": ["video", "third_party"],
      "created_at": "2026-03-02T10:04:31Z",
      "updated_at": "2026-06-18T14:20:07Z"
    }
  ],
  "next": null
}

La liste se lit du plus ancien au plus récent — order=desc pour l’inverse — et se parcourt avec next et after, comme toutes les listes.

Où un champ s’applique

Un champ s’applique à un asset quand son workspace et son type sont ceux qu’il vise : workspace_id vaut null ou le workspace de l’asset, et asset_types vaut null ou contient le type de l’asset. Écrire un champ qui ne s’applique pas à l’asset est refusé par un 400.

Les types, et la forme de leur valeur

Une valeur a la forme que lui donne le type de son champ — la même à la lecture et à l’écriture :

• Rien n’est converti : 42 n’est pas un texte, et "true" n’est pas un booléen.
• Le label d’un link peut être omis à l’écriture ; à la lecture, il vaut null quand l’adresse s’affiche telle quelle.
• Une date écrite ailleurs que par l’API peut porter aussi une heure, AAAA-MM-JJTHH:MM:SS, avec un décalage facultatif : lisez les deux formes.
• Les champs record, json et file figurent dans la liste, mais leurs valeurs ne sont ni lues ni écrites ici pour l’instant.
• La liste des types peut s’allonger : lisez un type inconnu comme un champ que votre client ne lit ni n’écrit.

Les options d’un champ à choix

Une valeur de champ choice contient des identifiants d’options, pas leurs libellés. GET /v1/custom-fields/{field_id}/choices liste les options d’un champ — à part, parce qu’un champ peut en proposer des milliers :

curl https://api.videas.com/v1/custom-fields/0192a680-2e3f-7a4b-9c5d-6e7f8a9b0c1d/choices \
  -H "Authorization: Bearer $VIDEAS_API_KEY"

{
  "data": [
    { "id": "0192a681-3f4a-7b5c-8d6e-7f8a9b0c1d2e", "label": "Reportage" },
    { "id": "0192a681-4a5b-7c6d-9e7f-8a9b0c1d2e3f", "label": "Interview" },
    { "id": "0192a681-5b6c-7d7e-8f8a-9b0c1d2e3f4a", "label": "Conférence" }
  ],
  "next": null
}

• Lisez cette liste pour trouver l’id d’une option que vous connaissez par son libellé, et le libellé que désigne la valeur d’un asset.
• Elle se lit du plus ancien au plus récent, ce qui n’est pas l’ordre d’un formulaire : triez-les vous-même si vous les affichez.
• Une option retirée du champ n’est plus listée, et ne peut plus être choisie. Un asset qui l’avait choisie avant la garde, la relit par son id, et peut se la voir renvoyer.
• Un field_id qui n’est pas celui d’un champ choice répond 404.

Pour passer du libellé à l’identifiant, parcourez les options une fois et gardez la table :

import os

import requests

API = "https://api.videas.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VIDEAS_API_KEY']}"}

def option_ids(field_id):
    """{libellé: id} pour chaque option du champ."""
    ids, params = {}, {}
    while True:
        page = requests.get(f"{API}/custom-fields/{field_id}/choices", headers=HEADERS, params=params)
        page.raise_for_status()
        body = page.json()
        ids.update({option["label"]: option["id"] for option in body["data"]})
        if body["next"] is None:
            return ids
        params["after"] = body["next"]

Écrire les valeurs d’un asset

PATCH /v1/assets/{asset_id}/custom-fields prend une liste de valeurs, chacune désignant son champ par son id :

curl -X PATCH https://api.videas.com/v1/assets/0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6/custom-fields \
  -H "Authorization: Bearer $VIDEAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      {
        "field_id": "0192a680-1d2e-7f3a-8b4c-5d6e7f8a9b0c",
        "value": { "url": "https://example.com/recyclage-fibre-carbone", "label": "Le dossier complet" }
      },
      {
        "field_id": "0192a680-2e3f-7a4b-9c5d-6e7f8a9b0c1d",
        "value": "0192a681-3f4a-7b5c-8d6e-7f8a9b0c1d2e"
      }
    ]
  }'

• Les champs que vous nommez prennent les valeurs envoyées ; les autres gardent les leurs. Ce n’est pas une liste qui remplace tout.
• null vide un champ — comme une chaîne vide sur un text ou un long_text, et une liste vide sur un champ multiple. Un champ required ne peut pas être vidé : 400.
• Chaque valeur est tenue aux règles de son champ — la longueur d’un texte, les bornes d’un nombre, une option que le champ propose encore.
• 200 valeurs au plus par requête, un champ nommé une seule fois, et 256 Kio au plus par valeur.
• Tout ou rien : si une seule valeur est refusée, aucune n’est écrite.

La réponse est l’asset entier ; ses valeurs sont dans custom_fields, dans l’ordre d’un formulaire :

{
  "id": "0192a6e4-3b5c-7d6e-8f90-a1b2c3d4e5f6",
  "updated_at": "2026-10-15T08:30:14Z",
  "custom_fields": [
    {
      "field_id": "0192a680-2e3f-7a4b-9c5d-6e7f8a9b0c1d",
      "slug": "format",
      "label": "Format",
      "type": "choice",
      "value": "0192a681-3f4a-7b5c-8d6e-7f8a9b0c1d2e"
    },
    {
      "field_id": "0192a680-1d2e-7f3a-8b4c-5d6e7f8a9b0c",
      "slug": "lien-utile",
      "label": "Lien utile",
      "type": "link",
      "value": { "url": "https://example.com/recyclage-fibre-carbone", "label": "Le dossier complet" }
    }
  ]
}

(extrait : la réponse porte tous les champs de l’asset.)

• custom_fields ne liste que les champs qui s’appliquent à l’asset et dont il a une valeur ; les champs record, json et file n’y figurent pas encore.
• updated_at ne bouge pas quand ses valeurs changent.
• Renvoyer les valeurs que l’asset porte déjà ne change rien, et la dernière requête arrivée l’emporte.
• La modification est inscrite dans l’historique de l’asset sous le nom de la clé, et un asset validé dans le fonds commun de l’organisation est refusé par un 403 — comme pour ses textes et ses tags.

Erreurs

Toutes les erreurs ont le même corps — {"code": "…", "message": "…", "request_id": "…"}. Testez code ; message s’adresse à un humain et peut changer.

Pour aller plus loin

• Modifier un asset — ses textes et ses tags.
• Publier sur une chaîne — où un champ public est montré à son public.
• La référence de l’API, générée depuis son contrat.