Téléversements d’images

Lorsque vous créez ou mettez à jour un article via l’API publique, vous pouvez inclure des images dans le corps de l’article à l’aide d’URL externes ou d’URL de données base64. L’API les téléverse vers Ferndesk et les stocke sous forme de chemins d’actifs.

Endpoints

Le téléversement des images est géré automatiquement lorsque vous rédigez le contenu d’un article via ces endpoints :

• POST /articles

• PATCH /articles/:id

Sources d’images acceptées

Vous pouvez utiliser ces formats dans le champ src des nœuds d’image du corps de l’article :

• URL externes — URL absolues pointant vers des images hébergées ailleurs

• URL de données base64 — chaînes data:image/...;base64,...

• URL d’actifs Ferndesk — images déjà hébergées par Ferndesk via https://static.ferndesk.com/user-images/...

Exigences relatives aux URL d’images externes

Les URL externes doivent pointer vers une image accessible publiquement via HTTP ou HTTPS. Les URL qui ne respectent pas ces exigences sont rejetées lors de la requête d’écriture.

• Seules les URL http et https sont acceptées.

• L’URL doit aboutir à une adresse accessible publiquement. Les adresses qui ne sont pas accessibles publiquement sont rejetées, y compris lorsqu’une redirection y mène.

• Les redirections sont validées à chaque étape, dans la limite de cinq étapes.

• Les téléchargements sont limités à 50 MiB et doivent être terminés en moins de 45 secondes. Les images SVG sont limitées à 2 MiB.

• Les réponses servies avec des types HTML, XML, JavaScript, exécutables ou autres types similaires non sécurisés sont rejetées, même lorsque le nom de fichier ressemble à celui d’une image. Les fichiers SVG sont assainis avant leur stockage.

Lorsqu’une URL externe ne respecte pas l’une de ces exigences, l’API renvoie la réponse d’échec du téléversement décrite dans la section Réponses d’erreur.

Fonctionnement

Lorsque vous envoyez une requête d’écriture, l’API :

• Téléverse les URL externes et les URL de données base64 vers les serveurs Ferndesk

• Remplace les valeurs src d’origine dans l’article stocké par les nouveaux chemins Ferndesk

• Laisse en place les images déjà hébergées par Ferndesk sans les téléverser à nouveau ; les URL statiques Ferndesk sont normalisées en chemins d’actifs

Si la même source d’image apparaît plusieurs fois dans une même requête, elle est téléversée une seule fois et toutes les références partagent le même chemin.

Réponses d’erreur

Si une image ne peut pas être traitée, l’API renvoie une erreur explicite et l’article n’est pas enregistré.

Base64 malformé

400 avec :

{
  "error": "Image data URL must contain valid base64 data",
  "code": "invalid_request"
}

Échec du téléversement

502 avec :

{
  "error": "Unable to upload one or more article images",
  "code": "image_upload_failed"
}

Ressources associées

• Présentation de l’API Ferndesk

• Authentification