KoKonna Open API

Affichez des photos de famille, des bulletins quotidiens et vos propres automatisations sur un cadre KoKonna. Envoyez-les via notre cloud depuis n’importe où, ou directement au cadre par le Wi‑Fi de votre domicile.

POSThttps://api.kokonna.art/openapi/upload Authorization: Bearer <API_KEY> Content-Type: application/json { "base64": "/9j/4AAQSkZJRg…", "name": "morning.jpg" }

200 OK{ "id": 789, "counter": 10 }

Importer une image Elle devient l’image active dès que le cadre se synchronise.

Quelle API utiliser ?Comparer Cloud et local

Ce qui change	API Cloud	API locale
Mode du cadre	Géré via l’application KoKonna	Mode local, géré dans l’interface web du cadre
Destination des requêtes	`https://api.kokonna.art/openapi`	`http://<frame-ip>/api/v1`
Connexion	HTTPS via Internet	HTTP sur le même réseau local de confiance, pendant que le cadre est éveillé
Clé d’accès	Clé API de l’appareil, dans les réglages du cadre de l’application	Un jeton distinct de 32 caractères, dans Settings → Local API
Envoi d’une image	Base64 dans du JSON ; la nouvelle image devient active	JPEG en multipart, ou Y4 pour les cadres de 28,5 pouces ; enregistrement possible sans affichage
Sélection d’une image	ID ou nom de l’image dans le cloud	Nom de fichier renvoyé par le cadre, par exemple `local_3.jpg`
Limites	20 requêtes par minute et par clé ; 50 MB par requête	16 MiB par import ; les requêtes doivent tenir dans une fenêtre d’éveil

Utilisez l’API qui correspond au mode actuel du cadre. En mode local, le cadre conserve sa propre photothèque et l’application KoKonna ne la gère pas : les clés cloud, les ID d’image et les imports JSON ne s’appliquent donc pas à l’API locale.

Accédez à votre cadre via le cloud

Consultez les informations de l’appareil, importez et gérez des images, et changez ce qu’affiche un cadre KoKonna, depuis n’importe où.

Choisissez l’API Cloud pour une application, un service hébergé ou des mises à jour envoyées depuis l’extérieur du domicile. Elle fonctionne avec les cadres gérés dans l’application KoKonna. Pour un cadre en mode local, utilisez l’API locale.

URL de base: https://api.kokonna.art/openapi
Transport: HTTPS
Authentification: Jeton Bearer
Format: JSON

Conçue pour des intégrations légères

Usages courants de l’API Cloud avec les cadres :

Des photos de famille depuis n’importe où

Envoyez une nouvelle photo de vacances sur un cadre familial depuis votre propre application ou service, puis vérifiez qu’elle a bien été synchronisée.
Tableau de bord de l’état des appareils

Surveillez le heartbeat, la batterie, l’état de charge, la géométrie de l’écran et l’état de synchronisation de vos cadres.
Gestion de la galerie

Listez les images existantes, supprimez celles qui sont obsolètes et choisissez l’image affichée.
Publication planifiée

Laissez votre backend transformer un menu du jour, un agenda ou le planning d’un atelier en image, puis la publier sur le cadre.
Intégrations d’agents IA

Rendez visibles les œuvres générées, les résultats de tâches, les bulletins et les mises à jour contextuelles.

Donnez à votre agent un ensemble d’outils pour le cadre

OpenClaw, Claude Code, ChatGPT ou tout agent capable d’appeler des outils peut piloter un cadre KoKonna grâce à une petite intégration côté serveur. Conservez la clé de l’appareil dans l’environnement d’exécution de l’agent, associez les opérations de l’API à des outils, et laissez l’agent inspecter, choisir, importer et afficher des œuvres.

Configuration initiale

Obtenir la clé
Copiez la clé API de l’appareil depuis les réglages du cadre dans l’application KoKonna.
La garder privée
Stockez-la dans les secrets côté serveur de l’agent, jamais dans le code client.
Déclarer les outils
Associez les opérations de l’API ci-dessous à des outils que l’agent peut appeler.
Environnement
```
BASE_URL=https://api.kokonna.art/openapi
API_KEY=<DEVICE_API_KEY>
```

À chaque demande

« Affiche un paysage bleu et paisible dans l’atelier. » L’agent vérifie le cadre, réutilise ou crée une œuvre, l’affiche, puis confirme l’image active.

DemanderL’utilisateur décrit ce qu’il souhaite voir au mur.
InspecterLire l’état du cadre et les images existantes.
AfficherRéutiliser une image ou en importer une nouvelle.
VérifierContrôler l’appareil et rendre compte du résultat.

Outil de l’agent	Opération de l’API	Rôle
`get_frame_status`	`POST /device`	Vérifier la connexion, la batterie, la synchronisation et l’image actuelle.
`list_frame_images`	`POST /listImages`	Rechercher une œuvre existante avant d’importer un doublon.
`upload_frame_image`	`POST /upload`	Importer une œuvre en base64 brut et la rendre active.
`display_frame_image`	`POST /displayImageById`	Passer à une image existante à partir de son ID.
`delete_frame_image`	`POST /deleteImage`	Supprimer une image, uniquement après confirmation de l’utilisateur.

Modèle d’instructions pour l’agent

Prompt système

You control a KoKonna Frame with the provided tools.

1. Inspect the frame before changing it when its state is unknown.
2. Reuse a suitable image from the library when possible.
3. For new artwork: generate image → encode raw base64 → upload.
4. Remember that upload makes the new image active immediately.
5. Ask for confirmation before deleting any image.
6. After a write action, check device status and report the result.

S’authentifier avec la clé de l’appareil

Envoyez un jeton Bearer dans l’en-tête Authorization.
Le jeton est la clé API de l’appareil affichée dans les réglages du cadre.
Envoyez du JSON avec l’en-tête Content-Type: application/json.

En-têtes de requête

Authorization: Bearer <API_KEY>
Content-Type: application/json

Limitation du débit

20 requêtes par minute et par clé d’appareil

Au-delà de cette limite, l’API renvoie HTTP 429. Patientez un instant, puis réessayez.

Réponse 429

{ "message": "Too many requests, please try again later." }

Opérations sur l’appareil et les images

Tous les chemins commencent par https://api.kokonna.art/openapi.

POST/device

Obtenir les informations de l’appareil

Corps de la requête : {} ou omis.

Réponse 200

{
  "firmware": "B100V050610",
  "nickname": "KoKonna",
  "lastHeartbeat": "2026-06-16T06:56:25.782Z",
  "isCharging": false,
  "batteryLevel": 100,
  "sdUsedSize": 0,
  "switchType": "queue",
  "switchMinute": 60,
  "imageId": 423,
  "coverId": null,
  "timezone": "America/Adak",
  "point": 30,
  "screenWidth": 800,
  "screenHeight": 480,
  "screenRotate": 270,
  "synced": false,
  "online": false
}

Description des champs

firmware: Version actuelle du firmware.
nickname: Nom de l’appareil.
lastHeartbeat: Horodatage ISO 8601 du dernier heartbeat.
isCharging, batteryLevel: État d’alimentation actuel.
sdUsedSize: Espace utilisé sur la carte SD, en octets.
switchType, switchMinute: Mode de changement d’image (queue ou random) et intervalle en minutes.
imageId, coverId: ID de l’image actuelle et de l’image de couverture.
screenWidth, screenHeight, screenRotate: Géométrie de l’écran.
synced, online: Indique si la dernière image a été appliquée et si le cadre est connecté.

cURL

curl -X POST https://api.kokonna.art/openapi/device \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/upload

Importer une image

Corps de la requête

{
  "base64": "/9j/4AAQSkZJRgABAQEAAAAAAAD...",
  "name": "photo.jpg"
}

base64 est obligatoire : données d’image en base64 brut, sans préfixe d’URL de données tel que data:image/jpeg;base64,.
Le compteur d’images du cadre augmente et la nouvelle image devient active.
name est facultatif ; par défaut, il reprend le nom du fichier d’origine.
Les images sont recadrées à la zone d’affichage : respectez si possible le format de l’écran.

Réponse 200

{ "id": 789, "counter": 10 }

id est l’ID de la nouvelle image ; counter est le compteur d’images mis à jour.

cURL

curl -X POST https://api.kokonna.art/openapi/upload \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"base64":"<BASE64_DATA>","name":"photo.jpg"}'

POST/listImages

Lister les images

Corps de la requête : {} ou omis.

Réponse 200

{
  "total": 2,
  "list": [
    {
      "id": 789,
      "name": "photo.jpg",
      "fileId": "abc123.jpg",
      "size": 182736,
      "type": "image/jpeg",
      "width": 800,
      "height": 480,
      "createdAt": "2026-05-14T08:00:00.000Z",
      "updatedAt": "2026-05-14T08:00:00.000Z",
      "current": true
    }
  ]
}

total: Nombre d’images sur l’appareil.
list: Images, de l’ID le plus récent au plus ancien.
current: true pour l’image active sur le cadre.

cURL

curl -X POST https://api.kokonna.art/openapi/listImages \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/deleteImage

Supprimer une image

Corps de la requête

{ "imageId": 123 }

imageId est obligatoire et doit appartenir à l’appareil.
Le fichier image et son enregistrement sont supprimés ensemble, et le compteur d’images augmente.
Si vous supprimez l’image active, le cadre passe à la suivante disponible.
S’il ne reste aucune image, l’image actuelle devient null.

Réponse 200

{
  "success": true,
  "id": 123,
  "imageId": 122,
  "counter": 11
}

id: ID de l’image supprimée.
imageId: Image active après la suppression, ou null s’il n’en reste aucune.
counter: Compteur d’images mis à jour.

Erreurs

500 avec { "message": "imageId is empty" } lorsque l’ID est absent ou invalide.
500 avec { "message": "image not found" } lorsque l’image n’appartient pas à l’appareil.

cURL

curl -X POST https://api.kokonna.art/openapi/deleteImage \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageId":123}'

GET/image/:apikey/:imageId

Télécharger une image

apikey: Clé API de l’appareil, dans les réglages du cadre.
imageId: ID de l’image renvoyé par les endpoints d’import ou de liste.

La clé figure dans le chemin de l’URL : aucun en-tête Authorization n’est nécessaire. Traitez ces URL comme privées.

Renvoie le fichier image d’origine stocké, sous forme de flux binaire.
L’image doit appartenir à l’appareil identifié par apikey.
Le type de contenu dépend de l’extension du fichier stocké, généralement image/jpeg.

Erreurs

404 avec { "message": "image not found" } pour un ID d’image invalide ou sans rapport avec l’appareil.
500 avec { "message": "can not find robot <apikey>" } pour une clé d’appareil inconnue.

cURL

curl -L "https://api.kokonna.art/openapi/image/<API_KEY>/123" \
  -o image.jpg

POST/displayImageById

Afficher une image par son ID

Corps de la requête

{ "imageId": 123 }

Renvoie { "success": true }, ou 500 avec { "message": "image not found" } si aucune image ne porte ce nom.

cURL

curl -X POST https://api.kokonna.art/openapi/displayImageById \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageId":123}'

POST/displayImageByName

Afficher une image par son nom

Corps de la requête

{ "imageName": "photo.jpg" }

Renvoie { "success": true }, ou 500 avec { "message": "image not found" } si aucune image ne porte ce nom.

cURL

curl -X POST https://api.kokonna.art/openapi/displayImageByName \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"imageName":"photo.jpg"}'

Gestion des erreurs

Les erreurs renvoient un statut HTTP et un message JSON.

Statut	Cas	Corps
404 Introuvable	La méthode indiquée dans l’URL n’existe pas.	`{ "message": "can not find method <method_name>" }`
429 Trop de requêtes	La limite de débit a été dépassée.	`{ "message": "Too many requests, please try again later." }`
500 Erreur serveur	Aucun appareil ne correspond à la clé, ou une autre erreur côté serveur s’est produite.	`{ "message": "can not find robot <apikey>" }` or `{ "message": "<error_message>" }`

Taille des données

L’API Cloud accepte les requêtes jusqu’à 50 MB : vos imports en base64 doivent rester sous cette taille. L’API locale a ses propres formats et limites d’import.

Vos photos, votre Wi‑Fi, vos automatisations

En mode local, vous importez des photos, choisissez ce qui s’affiche et lancez un diaporama depuis l’interface web du cadre. Activez l’API locale pour qu’un ordinateur ou un serveur domestique puisse faire de même via votre Wi‑Fi.

URL de base: http://<frame-ip>/api/v1
Connexion: HTTP local, port 80
Accès: Jeton Bearer local
Disponibilité: Pendant que le cadre est éveillé

Vous souhaitez simplement importer des photos vous-même ? Utilisez l’interface web du cadre, sans aucune ligne de code. Activez l’API locale lorsque vous voulez créer une automatisation. Ces instructions concernent les firmwares qui proposent Settings → Local API.

De petites routines, rendues visibles

Exécutez votre intégration sur un ordinateur, un Raspberry Pi, un NAS ou un serveur domestique capable de joindre le cadre. Vous fournissez le planning, le contenu et la logique.

Un album de famille depuis votre NAS

Importez un lot de photos depuis un dossier partagé avec show=0, puis activez un diaporama quotidien. Aucun passage par le cloud.
Importer un album
Une scène pour le retour à la maison

Laissez Home Assistant ou Node-RED sélectionner une image de bienvenue enregistrée. Si le cadre est en veille, envoyez la requête lors de la prochaine fenêtre d’éveil.
Sélectionner une image enregistrée
Un planning familial du matin

Générez sous forme d’image l’agenda, la météo ou les tâches du jour sur votre serveur domestique, importez-la, puis vérifiez que l’écran s’est rafraîchi.
Publier votre première image
Un affichage pour un atelier ou un café

Enregistrez à l’avance des horaires d’ouverture, un menu ou le planning d’un atelier, puis sélectionnez-en un par son nom de fichier, ou utilisez le diaporama.
Configurer un diaporama
Un album sans Internet

Conservez une collection sur le cadre et faites-la défiler localement. Votre routeur fournit le Wi‑Fi même lorsque la connexion Internet est coupée.
Se connecter en mode local
Des œuvres créées par un agent local

Laissez un agent de votre réseau lire la taille du cadre, importer une image adaptée et confirmer son affichage.
Inspecter d’abord le cadre

Connectez-vous une fois, puis automatisez

Ouvrir le point d’accès du cadre
Redémarrez le cadre et suivez les instructions à l’écran. Rejoignez le réseau KOKONNA-XXXXXX qu’il affiche, puis ouvrez l’adresse indiquée à l’écran dans votre navigateur, généralement http://192.168.4.1. Restez connecté même si votre téléphone signale l’absence d’Internet.
Activer le mode local
Confirmez le mode local dans le navigateur s’il n’est pas déjà activé. Désormais, vous gérez les photos et les réglages ici ; dans ce mode, l’application KoKonna ne gère pas le cadre.
Activer l’API locale
Ouvrez Settings → Local API, activez l’interrupteur et saisissez le nom et le mot de passe de votre réseau Wi‑Fi 2,4 GHz. Commencez avec les valeurs par défaut (300 secondes de veille et 10 secondes d’éveil), puis choisissez « Save Local API ».
Copier votre jeton d’accès local
Conservez le jeton de 32 caractères et l’adresse LAN affichés dans les réglages. Ce jeton est distinct de votre clé API Cloud.
Lancer le cycle de veille et d’éveil
Choisissez « Close Wi‑Fi and sleep », ou fermez la page et laissez le point d’accès expirer. Reconnectez votre ordinateur au Wi‑Fi de votre domicile. À son prochain réveil, le cadre rejoint ce réseau et démarre son service local.
Ouvrir le cadre sur votre réseau domestique
Pendant que le cadre est éveillé, ouvrez l’adresse enregistrée, par exemple http://kokonna-xxxxxx.local, et saisissez le jeton. Si le nom n’est pas résolu, utilisez l’adresse IP du cadre indiquée dans la liste des appareils de votre routeur ; une réservation DHCP la garde fixe.

Le nom d’hôte correspond au nom du point d’accès en minuscules, où xxxxxx représente les six derniers caractères de l’adresse MAC. L’adresse du point d’accès sert uniquement à la configuration et diffère de l’adresse sur votre réseau domestique.

Le navigateur mémorise le jeton pour cette adresse ; il vous sera redemandé si vous passez du nom d’hôte à l’IP, ou à un autre navigateur. Pendant vos essais, laissez ouverte la page de contrôle connectée : elle envoie un heartbeat toutes les 5 secondes pour maintenir le cadre éveillé. Fermez-la ensuite pour que le cadre puisse se mettre en veille.

De la photo à l’écran

Exécutez ces commandes dans un terminal sur le même réseau. Remplacez l’IP et le jeton par les vôtres, et laissez ouverte la page connectée du cadre. Ce guide concerne les cadres dont l’uploadFormat est jpg ; les cadres de 28,5 pouces utilisent l’import Y4.

Vérifier la connexion et la taille d’image
Terminal
```
FRAME='http://192.168.1.50'
TOKEN='YOUR_LOCAL_ACCESS_TOKEN'

curl --connect-timeout 3 --max-time 5 \
  -H "Authorization: Bearer $TOKEN" \
  "$FRAME/api/v1/info"
```
Lisez uploadFormat, uploadWidth et uploadHeight, recadrez votre image à cette taille et enregistrez-la en JPEG baseline (non progressif). Si la requête expire, attendez une fenêtre d’éveil : une requête HTTP ne peut pas réveiller le cadre.
Enregistrer votre photo
Terminal
```
curl -H "Authorization: Bearer $TOKEN" \
  -F 'image=@photo.jpg;filename=photo.jpg;type=image/jpeg' \
  "$FRAME/api/v1/upload?show=0&uploadId=first-photo-001"
```
En cas de succès, la réponse est HTTP 201 avec un nom de fichier, par exemple {"file":"local_3.jpg"}. Avec show=0, la photo est enregistrée sans modifier l’écran. Utilisez un nouvel uploadId pour chaque image et ne le réutilisez que pour relancer le même import.
Afficher la photo enregistrée
Terminal
```
curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'name=local_3.jpg' \
  "$FRAME/api/v1/show"
```
Utilisez le nom de fichier obtenu lors de l’import. HTTP 200 avec {"current":"local_3.jpg"} signifie que la requête a été acceptée ; le rafraîchissement de l’écran e-paper se termine séparément.
Vérifier que l’écran a fini de se rafraîchir
Terminal
```
curl -H "Authorization: Bearer $TOKEN" "$FRAME/api/v1/info"
```
Interrogez le cadre environ toutes les 2 secondes tant que refreshing vaut true. L’opération est terminée lorsque refreshing=false, displayStatus="succeeded", et que lastDisplayFile et displayed correspondent tous deux à votre nom de fichier. Si le statut est failed, la photo est peut-être enregistrée, mais l’écran n’a pas été mis à jour. Arrêtez ensuite d’interroger le cadre et fermez la page de contrôle pour qu’il puisse se mettre en veille.

Composer avec la fenêtre d’éveil

Entre deux connexions, le cadre se met en veille pour économiser l’énergie, et l’écran e-paper conserve son image. Avec les valeurs par défaut, il dort 300 secondes, rejoint le Wi‑Fi, puis attend jusqu’à 10 secondes d’inactivité une requête valide. La durée de veille n’inclut ni la connexion, ni l’import, ni le rafraîchissement : il ne s’agit donc pas d’un cycle exact de cinq minutes.

VeilleL’API est inaccessible.
ConnexionLe cadre rejoint votre Wi‑Fi enregistré.
ServiceLes requêtes maintiennent la fenêtre ouverte.
FinLe rafraîchissement se termine, puis le cadre se met en veille.

Réglages de temporisation de l’API locale
Réglage	Valeur par défaut et plage	Effet
`apiEnabled`	Désactivé ; 0 ou 1	Exécute le service planifié sur le Wi‑Fi de votre domicile.
`sleepSeconds`	300 ; 60–3600 secondes	Durée de veille entre deux fenêtres de service.
`awakeSeconds`	10 ; 10–3600 secondes	Délai d’inactivité après la connexion au Wi‑Fi. Chaque requête authentifiée le relance.

Votre première intégration: Une durée d’éveil de 60 secondes vous laisse le temps de tester. Des fenêtres plus longues et des interrogations fréquentes consomment davantage d’énergie.
Mises à jour planifiées: Préparez d’abord l’image. Relancez ensuite GET /info toutes les quelques secondes avec des délais d’expiration courts, à des intervalles inférieurs à awakeSeconds, et arrêtez-vous à l’échéance de votre choix.
Sessions plus longues: Envoyez un POST /heartbeat authentifié toutes les 5 secondes. Les imports et les rafraîchissements terminés prolongent aussi la fenêtre ; le chargement de la page d’accueil publique, non.
Pendant un rafraîchissement: Patientez avant la prochaine opération sur une image. 423 signifie que le cadre est occupé, avec Retry-After: 2. Les imports et les rafraîchissements se terminent toujours avant la mise en veille.
Diaporamas: L’intervalle du diaporama est indépendant de l’intervalle de veille. Une diapositive arrivée à échéance change au premier réveil qui suit son intervalle.
En cas d’échec du Wi‑Fi: Le cadre essaie pendant environ 10 secondes, puis attend le cycle suivant. Il ne rouvre pas de lui-même le point d’accès : redémarrez-le pour corriger les réglages réseau. La protection contre la batterie faible reste prioritaire.

Une requête HTTP ordinaire ne peut pas réveiller un cadre en veille : mettez donc en file d’attente les contenus urgents pour sa prochaine connexion. Sur les petits cadres, la charge peut remplacer la veille profonde par une période d’inactivité Wi‑Fi coupé ; l’accès local passe toujours par des fenêtres de service périodiques.

Référence de l’API locale

Tous les chemins commencent par http://<frame-ip>/api/v1. Sur le Wi‑Fi domestique, chaque requête doit inclure Authorization: Bearer <LOCAL_TOKEN>, y compris les téléchargements d’images. Les requêtes passant par le point d’accès n’ont pas besoin de jeton, car celui-ci sert de point d’entrée pour la configuration.

Les exemples réutilisent FRAME et TOKEN définis dans Votre première image. Envoyez les paramètres POST ordinaires sous forme de données de formulaire (-d ou --data-urlencode), et non en JSON. Il n’y a ni TLS ni CORS : appelez l’API depuis un client de votre réseau de confiance et ne l’exposez pas sur Internet.

Aperçu des endpoints

Méthode	Chemin	Utilisation
GET	`/info`	Lire les détails de l’appareil et le résultat de l’affichage.
GET	`/state`	Lire l’état complet de l’interface web, noms des images compris.
GET	`/images`	Lister l’album local.
GET	`/image`	Télécharger une photo ou une miniature.
GET, POST	`/config`	Lire ou modifier les réglages Wi‑Fi et de réveil.
POST	`/upload`	Importer un JPEG sur les petits cadres compatibles.
POST	`/upload-y4`	Importer des données Y4 et un aperçu JPEG sur les cadres de 28,5 pouces.
POST	`/upload-y4-bin`	Envoyer le même contenu Y4 en un seul corps binaire.
POST	`/show`	Afficher une photo enregistrée.
POST	`/next`, `/previous`	Parcourir l’album.
POST	`/delete`	Supprimer une photo et les fichiers associés.
POST	`/settings`	Régler le comportement du diaporama et l’orientation.
POST	`/heartbeat`, `/sleep`	Maintenir la session ouverte ou y mettre fin.

GET/info, /state

Connaître votre cadre

Les deux renvoient HTTP 200 en JSON ; /state inclut en plus un tableau images de noms de fichiers. Utilisez /info pour vérifier que le cadre est prêt et confirmer les résultats d’affichage, même lorsque la carte SD n’est pas disponible.

apiVersion, enabled, activationId: Version de l’API, état du mode local et ID d’activation. Une réinitialisation suivie d’une réactivation modifie cet ID.
serial, firmware, battery, charging: ID de l’appareil, version du firmware, niveau de batterie et état de charge.
networkMode, ip, ssid, hostname: ap pour le point d’accès ou sta pour le Wi‑Fi domestique, ainsi que l’adresse et le nom du réseau actuels.
wifiConnected, wifiRssi: État du Wi‑Fi domestique et intensité du signal ; false et 0 en mode point d’accès.
sdReady, storageTotalMB, storageUsedMB: Disponibilité, capacité et utilisation du stockage.
current, displayed: Le nom du fichier sélectionné et la dernière photo affichée avec succès. La sélection change avant que l’écran ait fini de se rafraîchir.
refreshing, displayStatus, lastDisplayFile: Indique si un affichage est en attente ; idle, pending, succeeded ou failed ; et le dernier fichier demandé depuis le démarrage.
showingConnectionGuide: Indique si le guide de connexion est affiché à l’écran. displayed désigne toujours la photo précédente.
panelWidth, panelHeight: Taille physique de la dalle, en pixels.
uploadWidth, uploadHeight, uploadFormat: Taille recommandée pour l’orientation actuelle, et jpg ou y4.
maxUploadBytes, frameColorMode: Limite d’import (16 MiB) et mode couleur du modèle.
apiEnabled, sleepSeconds, awakeSeconds: Accès et temporisation de l’API locale.
slideshow, order, interval, orientation: Réglages de lecture actuels ; interval est exprimé en secondes.

GET/images, /image

Parcourir votre album

Réponse 200 de /images

{
  "images": ["local_1.jpg", "local_2.jpg"],
  "current": "local_2.jpg",
  "displayed": "local_1.jpg",
  "refreshing": true
}

Télécharger une miniature

curl -H "Authorization: Bearer $TOKEN" \
  "$FRAME/api/v1/image?name=local_1.jpg&thumbnail=1" \
  -o thumbnail.jpg

Utilisez les noms de fichiers renvoyés par le cadre. Omettez thumbnail=1 pour obtenir le JPEG enregistré ; en l’absence de miniature, le JPEG est renvoyé de toute façon. Sur les cadres de 28,5 pouces, l’entrée .jpg est l’aperçu, et les données d’affichage se trouvent dans le fichier .y4 correspondant. Les téléchargements peuvent être indisponibles pendant un rafraîchissement.

POST/upload

Importer un JPEG

Pour uploadFormat="jpg". Envoyez un JPEG baseline de 16 MiB maximum, accompagné si vous le souhaitez d’une miniature JPEG ne dépassant pas 640 × 640 pixels. Recadrez à la taille recommandée ; le firmware peut redimensionner les JPEG valides.

cURL

curl -H "Authorization: Bearer $TOKEN" \
  -F 'image=@photo.jpg;filename=photo.jpg;type=image/jpeg' \
  -F 'thumbnail=@thumbnail.jpg;filename=thumbnail.jpg;type=image/jpeg' \
  "$FRAME/api/v1/upload?show=0&uploadId=album-photo-001"

Envoyez d’abord l’image principale, puis la miniature facultative nommée thumbnail.jpg. Évitez le mot « thumbnail » dans le nom du fichier principal.
show=0 enregistre seulement, ce qui convient aux imports par lots. Omettez-le, ou utilisez show=1, pour enregistrer et afficher.
HTTP 201 renvoie le nom de fichier attribué, par exemple {"file":"local_3.jpg"}. Conservez-le pour les requêtes d’affichage ou de suppression ultérieures.
Les paramètres de requête facultatifs jpgBytes et thumbnailBytes déclarent la taille des fichiers pour des contrôles d’intégrité supplémentaires.
uploadId accepte jusqu’à 64 lettres, chiffres, traits d’union ou tirets bas. Seul le dernier import réussi est mémorisé, y compris après un redémarrage. Si une réponse se perd, relancez d’abord le même fichier avec le même ID. Il ne s’agit pas d’un contrôle permanent des doublons.

POST/upload-y4, /upload-y4-bin

Importer sur les cadres de 28,5 pouces

Ces modèles nécessitent des données d’affichage Y4 prêtes pour la dalle, accompagnées d’un aperçu JPEG ; l’endpoint JPEG ne peut pas les remplacer. Pour les imports manuels, l’interface web du cadre prépare l’image à votre place. Les intégrations personnalisées doivent produire le format Y4 décrit ci-dessous.

Format Y4 et exemples d’import

Préparez l’image pour l’orientation actuelle et la taille physique de la dalle. En paysage, faites-la pivoter dans le sens horaire vers l’orientation physique, appliquez un miroir horizontal, puis regroupez deux pixels par octet : x pair dans les 4 bits de poids faible, x impair dans les 4 bits de poids fort. Les codes couleur natifs sont noir 0, blanc 7, jaune 2, bleu 1, rouge 4 et vert 3. Les données Y4 doivent faire exactement panelWidth × panelHeight / 2 octets ; du RGB brut ne fonctionnera pas.

Multipart : Y4 d’abord, puis la miniature JPEG obligatoire

curl -H "Authorization: Bearer $TOKEN" \
  -F 'display=@photo.y4;filename=photo.y4;type=application/octet-stream' \
  -F 'thumbnail=@thumbnail.jpg;filename=thumbnail.jpg;type=image/jpeg' \
  "$FRAME/api/v1/upload-y4?show=0&uploadId=poster-001"

Binaire : Y4 immédiatement suivi du JPEG

cat photo.y4 thumbnail.jpg > upload.bin
Y4_BYTES=$(wc -c < photo.y4 | tr -d '[:space:]')
THUMB_BYTES=$(wc -c < thumbnail.jpg | tr -d '[:space:]')

curl -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  -H "X-Upload-Y4-Bytes: $Y4_BYTES" \
  -H "X-Upload-Thumbnail-Bytes: $THUMB_BYTES" \
  -H 'X-Upload-Show: 0' \
  -H 'X-Upload-Id: poster-002' \
  --data-binary @upload.bin \
  "$FRAME/api/v1/upload-y4-bin"

Le corps binaire ne comporte aucun séparateur, et les autres clients doivent envoyer le Content-Length exact. Les deux en-têtes de nombre d’octets sont obligatoires et la miniature ne doit pas être vide. X-Upload-Show: 0 enregistre seulement ; toute autre valeur affiche l’image. X-Upload-Id est facultatif et permet de relancer comme uploadId. Les paramètres de requête ne peuvent pas remplacer ces en-têtes.

Les données Y4 et la miniature doivent tenir ensemble dans 16 MiB, et la miniature dans 640 × 640 pixels. Les deux routes renvoient HTTP 201 avec un nom de fichier d’album .jpg, par exemple {"file":"local_3.jpg"} ; utilisez-le pour afficher l’image.

POST/show, /next, /previous, /delete

Piloter l’album

cURL

# Display a saved image
curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'name=local_3.jpg' "$FRAME/api/v1/show"

# Move through the album (no request body)
curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/next"
curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/previous"

Show, next et previous renvoient HTTP 200 avec {"current":"local_3.jpg"} lorsque la requête est acceptée. Next et previous suivent l’ordre de lecture et reviennent au début une fois en bout de liste ; un album vide renvoie 404. Attendez la fin de chaque rafraîchissement avant d’envoyer une nouvelle modification.

Supprimer une image dont vous n’avez plus besoin

curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'name=local_1.jpg' "$FRAME/api/v1/delete"

La suppression efface la photo, sa miniature et les éventuelles données Y4, et renvoie ok, current et refreshing. Supprimer la photo sélectionnée sélectionne la suivante ; supprimer la dernière photo affiche le guide d’import. Vérifiez le nom du fichier avant de supprimer.

POST/settings

Diaporama et orientation

Par exemple, faire défiler l’album toutes les heures en mode portrait :

cURL

curl -H "Authorization: Bearer $TOKEN" \
  -d 'slideshow=1&order=sequence&interval=3600&orientation=portrait' \
  "$FRAME/api/v1/settings"

Envoyez les quatre paramètres à chaque requête :

slideshow: 0 désactivé, 1 activé.
order: sequence or random.
interval: 300, 3600, 21600, 43200, 86400 ou 604800 secondes : 5 minutes, 1 heure, 6 heures, 12 heures, 1 jour ou 1 semaine.
orientation: portrait or landscape.

La réponse HTTP 200 inclut orientationChanged, refreshing et la nouvelle taille d’import. Un changement d’orientation planifie un nouvel affichage : adaptez la taille de vos prochains imports en conséquence. Ces réglages ne modifient pas l’intervalle de veille de l’API locale.

GETPOST/config

Réglages réseau et de réveil

GET lit la configuration ; POST la modifie. Incluez apiEnabled=0 ou 1 à chaque fois ; les autres valeurs omises restent inchangées. Par exemple, pour allonger la fenêtre de test :

cURL

curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode 'apiEnabled=1' \
  --data-urlencode 'sleepSeconds=300' \
  --data-urlencode 'awakeSeconds=60' \
  "$FRAME/api/v1/config"

Les deux renvoient HTTP 200 avec apiEnabled, wifiSsid, sleepSeconds, awakeSeconds, token et hostname. Le mot de passe Wi‑Fi n’est jamais renvoyé. Gardez la réponse privée, car elle contient votre jeton d’accès.

wifiSsid est facultatif, limité à 32 octets, et ne peut pas être vide lors de l’activation de l’API. wifiPassword est facultatif, limité à 64 octets ; omettez-le pour le conserver, ou envoyez-le vide pour un réseau ouvert.
sleepSeconds : 60–3600. awakeSeconds : 10–3600. Les valeurs invalides renvoient 400 et ne modifient rien.
Un enregistrement depuis le Wi‑Fi domestique met fin à la fenêtre en cours après la réponse et tout affichage en attente ; le réveil suivant applique les nouveaux réglages. Un enregistrement via le point d’accès le laisse ouvert pour que vous puissiez copier le jeton.
Désactiver l’API locale arrête le service LAN planifié. Pour la réactiver, redémarrez le cadre et reconnectez-vous au point d’accès.

POST/heartbeat, /sleep

Poursuivre ou terminer

cURL

curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/heartbeat"

# After the display has finished refreshing:
curl -H "Authorization: Bearer $TOKEN" -X POST "$FRAME/api/v1/sleep"

Heartbeat renvoie 204 sans corps. Sleep renvoie 202, par exemple {"ok":true,"sleepSeconds":300,"timerWake":true}, et ferme le service peu après. Si un rafraîchissement est en attente, sleep renvoie 423 ; patientez puis réessayez. Lorsque l’API et le diaporama sont tous deux désactivés, timerWake vaut false, et vous devrez redémarrer le cadre pour vous reconnecter.

En cas de problème

Un délai de connexion dépassé n’est pas une erreur HTTP : le cadre est peut-être en veille ou encore en train de rejoindre le Wi‑Fi. La plupart des erreurs de l’API renvoient du JSON, par exemple {"error":"Image not found."} ; les téléchargements d’images peuvent renvoyer du texte brut.

Réponse	Que faire
400 Requête invalide	Lisez `error`. Vérifiez les champs du formulaire, le format de l’image, la taille du fichier et que le transfert est complet. L’échec des contrôles de stockage peut aussi renvoyer 400.
401 Non autorisé	Utilisez le jeton d’accès local avec l’en-tête Bearer exact ; une clé API Cloud ne fonctionnera pas. Les authentifications échouées ne prolongent pas la fenêtre d’éveil.
404 Introuvable	Vérifiez le chemin et utilisez un nom de fichier renvoyé par `/images`. Next et previous renvoient également 404 pour un album vide.
409 Mode local désactivé	Activez d’abord le mode local dans l’interface web du cadre.
423 Rafraîchissement en cours	Attendez la fin de l’affichage, puis réessayez. Respectez `Retry-After: 2` et suivez la progression avec `/info`.
500 Échec du stockage	Lisez le message et vérifiez la carte SD avant de relancer une suppression ou une autre opération de stockage.
503 Carte SD indisponible	Les opérations sur les images nécessitent la carte SD. Vérifiez `sdReady` avec `/info` ; les informations de l’appareil et les réglages restent accessibles.

Je n’arrive pas à joindre le cadre sur le Wi‑Fi domestique

Vérifiez que l’API locale est activée, que le cadre a quitté la configuration par point d’accès et que votre appareil peut communiquer avec les autres appareils du même réseau ; l’isolation d’un Wi‑Fi invité peut l’empêcher. Attendez la prochaine fenêtre d’éveil. Si le nom .local ne fonctionne pas, utilisez l’IP attribuée par le routeur. Si les informations Wi‑Fi sont erronées, redémarrez le cadre, rejoignez à nouveau son point d’accès et corrigez-les.

L’import a réussi, mais l’écran n’a pas changé

show=0 enregistre sans afficher : envoyez donc /show avec le nom de fichier renvoyé. Sinon, attendez refreshing=false et vérifiez displayStatus, lastDisplayFile et displayed. Une réponse HTTP réussie ne suffit pas à confirmer que l’écran s’est rafraîchi.

Le cadre reste en ligne plus longtemps que prévu

Une page de contrôle ouverte envoie un heartbeat toutes les 5 secondes, et les scripts de surveillance prolongent la fenêtre à chaque requête authentifiée. Fermez la page et cessez d’interroger le cadre lorsque vous avez terminé. Le cadre termine toujours les imports et les affichages avant de se mettre en veille.

J’ai perdu le jeton local, ou je veux réutiliser l’application

Pour retrouver votre jeton, redémarrez le cadre, rejoignez son point d’accès et ouvrez Settings → Local API. Pour revenir à l’application KoKonna, utilisez « Reset device » dans l’interface web. La réinitialisation efface toutes les images et tous les réglages locaux, y compris le Wi‑Fi enregistré et le jeton : faites d’abord une copie de vos photos.

Pays/région

Langue

KoKonna Open API

Accédez à votre cadre via le cloud

Conçue pour des intégrations légères

Des photos de famille depuis n’importe où

Tableau de bord de l’état des appareils

Gestion de la galerie

Publication planifiée

Intégrations d’agents IA

Donnez à votre agent un ensemble d’outils pour le cadre

Configuration initiale

À chaque demande

S’authentifier avec la clé de l’appareil

Limitation du débit

Opérations sur l’appareil et les images

Obtenir les informations de l’appareil

Description des champs

Importer une image

Lister les images

Supprimer une image

Erreurs

Télécharger une image

Erreurs

Afficher une image par son ID

Afficher une image par son nom

Gestion des erreurs

Taille des données

Vos photos, votre Wi‑Fi, vos automatisations

De petites routines, rendues visibles

Un album de famille depuis votre NAS

Une scène pour le retour à la maison

Un planning familial du matin

Un affichage pour un atelier ou un café

Un album sans Internet

Des œuvres créées par un agent local

Connectez-vous une fois, puis automatisez

De la photo à l’écran

Composer avec la fenêtre d’éveil

Référence de l’API locale

Aperçu des endpoints

Connaître votre cadre

Parcourir votre album

Importer un JPEG

Importer sur les cadres de 28,5 pouces

Piloter l’album

Diaporama et orientation

Réglages réseau et de réveil

Poursuivre ou terminer

En cas de problème