KoKonna Open API

家族の写真や毎日のブリーフィング、自作のオートメーションをKoKonnaフレームに表示できます。どこからでもクラウド経由で送ることも、ご自宅のWi‑Fiでフレームへ直接送ることもできます。

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 }

画像をアップロード フレームが同期するとすぐに、表示中の画像になります。
どちらのAPIを使えばよいですか？CloudとLocalの比較
項目 Cloud API Local API
フレームのモード KoKonnaアプリで管理 ローカルモード。フレームのブラウザ画面で管理
リクエストの送信先 https://api.kokonna.art/openapi http://<frame-ip>/api/v1
接続 インターネット経由のHTTPS 信頼できる同一ローカルネットワーク上のHTTP（フレームの起動中のみ）
アクセスキー アプリのフレーム設定にあるデバイスAPIキー Settings → Local API で発行される、別の32文字のトークン
画像の送信 JSON内のBase64。新しい画像が表示中になります JPEGのmultipart、28.5インチフレームはY4。表示せずに保存も可能
画像の選択 クラウドの画像IDまたは名前 フレームが返すファイル名（例：local_3.jpg）
制限 キーごとに毎分20リクエスト、1リクエストあたり50 MB 1回のアップロードにつき16 MiB。リクエストは起動ウィンドウ内に収める必要があります

フレームの現在のモードに合ったAPIを使用してください。ローカルモードではフレームが独自のフォトライブラリを保持し、KoKonnaアプリでは管理されません。そのため、クラウドのキー、画像ID、JSONアップロードはLocal APIでは使用できません。

クラウド経由でフレームにアクセス

デバイス情報の取得、画像のアップロードと管理、KoKonnaフレームの表示切り替えを、どこからでも行えます。

アプリ、ホスティングされたサービス、または外出先から送る更新には、Cloud APIを選んでください。KoKonnaアプリで管理しているフレームで動作します。ローカルモードのフレームには、Local APIを使用してください。

ベースURL
https://api.kokonna.art/openapi
通信方式
HTTPS
認証
Bearerトークン
形式
JSON

軽量な連携のために

Cloud APIとフレームの代表的な使い方：

  • どこからでも家族写真を

    自作のアプリやサービスから、家族のフレームに新しい旅行の写真を送り、同期されたことを確認します。

  • デバイス状態ダッシュボード

    複数のフレームのハートビート、バッテリー、充電状態、画面サイズ、同期状態を監視します。

  • ギャラリー管理

    既存の画像を一覧表示し、古いものを削除して、画面に表示する画像を選びます。

  • スケジュール配信

    毎日のメニュー、カレンダー、スタジオのスケジュールをバックエンドで画像に変換し、フレームに配信します。

  • AIエージェント連携

    生成したアート、タスクの結果、ブリーフィング、状況に応じた更新を、目に見える形にします。

エージェントにフレーム操作ツールを

OpenClaw、Claude Code、ChatGPTなど、ツール呼び出しに対応したエージェントであれば、小さなサーバーサイド連携を通じてKoKonnaフレームを操作できます。デバイスキーはエージェントの実行環境に置き、API操作をツールに割り当てれば、エージェントがアートの確認、選択、アップロード、表示を行えるようになります。

最初に一度だけ設定

  1. キーを取得

    KoKonnaアプリのフレーム設定から、デバイスAPIキーをコピーします。

  2. キーを非公開に保つ

    クライアントコードには含めず、エージェントのサーバーサイドのシークレットに保存します。

  3. ツールを登録

    以下のAPI操作を、エージェントが呼び出せるツールに割り当てます。

    環境
    BASE_URL=https://api.kokonna.art/openapi
API_KEY=<DEVICE_API_KEY>

リクエストごとに

「スタジオに静かな青い風景を飾って。」 エージェントはフレームを確認し、アートを再利用または作成して表示し、表示中の画像を確認します。
  1. 依頼ユーザーが壁に飾りたいものを伝えます。
  2. 確認フレームの状態と既存の画像を読み取ります。
  3. 表示既存の画像を再利用するか、新しい画像をアップロードします。
  4. 検証デバイスを確認し、結果を報告します。
エージェントツール API操作 用途
get_frame_status POST /device オンライン状態、バッテリー、同期、現在の画像を確認します。
list_frame_images POST /listImages 重複してアップロードする前に、既存のアートを探します。
upload_frame_image POST /upload 生のBase64データでアートをアップロードし、表示中にします。
display_frame_image POST /displayImageById IDを指定して既存の画像に切り替えます。
delete_frame_image POST /deleteImage ユーザーの確認後にのみ、画像を削除します。
エージェント指示テンプレート
システムプロンプト
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.

デバイスキーで認証

  • Authorization ヘッダーでBearerトークンを送信します。
  • トークンは、フレーム設定に表示されるデバイスAPIキーです。
  • Content-Type: application/json ヘッダーを付けてJSONを送信します。
リクエストヘッダー
Authorization: Bearer <API_KEY>
Content-Type: application/json

レート制限

20 リクエスト／分（デバイスキーごと）

制限を超えると HTTP 429 が返ります。少し待ってから再試行してください。

429レスポンス
{ "message": "Too many requests, please try again later." }

デバイスと画像の操作

すべてのパスは https://api.kokonna.art/openapi から始まります。

POST/device

デバイス情報を取得

リクエストボディ：{} または省略。

レスポンス 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
}

フィールドの説明

firmware
現在のファームウェアバージョン。
nickname
デバイスのニックネーム。
lastHeartbeat
最後のハートビートのISO 8601タイムスタンプ。
isCharging, batteryLevel
現在の電源状態。
sdUsedSize
SDカードの使用容量（バイト）。
switchType, switchMinute
画像の切り替え方式（queue または random）と間隔（分）。
imageId, coverId
現在の画像とカバーのID。
screenWidth, screenHeight, screenRotate
ディスプレイのサイズ情報。
synced, online
最新の画像が反映済みかどうか、およびフレームが接続中かどうか。
cURL
curl -X POST https://api.kokonna.art/openapi/device \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/upload

画像をアップロード

リクエストボディ
{
  "base64": "/9j/4AAQSkZJRgABAQEAAAAAAAD...",
  "name": "photo.jpg"
}
  • base64 は必須です。data:image/jpeg;base64, のようなデータURLの接頭辞を付けない、生のBase64画像データを指定します。
  • フレームの画像カウンターが増え、新しい画像が表示中になります。
  • name は省略可能で、省略時は元のファイル名になります。
  • 画像は表示領域に合わせてトリミングされるため、できるだけ画面の縦横比に合わせてください。
レスポンス 200
{ "id": 789, "counter": 10 }

id は新しい画像のID、counter は更新後の画像カウンターです。

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

画像の一覧

リクエストボディ：{} または省略。

レスポンス 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
デバイス上の画像の数。
list
画像（IDの新しい順）。
current
フレームで表示中の画像は true。
cURL
curl -X POST https://api.kokonna.art/openapi/listImages \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/deleteImage

画像を削除

リクエストボディ
{ "imageId": 123 }
  • imageId は必須で、そのデバイスに属している必要があります。
  • 画像ファイルとそのレコードが同時に削除され、画像カウンターが増えます。
  • 表示中の画像を削除すると、フレームは次に利用可能な画像に切り替わります。
  • 画像が残っていない場合、現在の画像は null になります。
レスポンス 200
{
  "success": true,
  "id": 123,
  "imageId": 122,
  "counter": 11
}
id
削除された画像のID。
imageId
削除後に表示中の画像。画像が残っていない場合は null。
counter
更新後の画像カウンター。

エラー

  • IDがない、または無効な場合は、500 と { "message": "imageId is empty" } が返ります。
  • 画像がそのデバイスに属していない場合は、500 と { "message": "image not found" } が返ります。
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

画像をダウンロード

apikey
フレーム設定にあるデバイスAPIキー。
imageId
アップロードまたは一覧のエンドポイントが返す画像ID。

キーはURLのパスに含まれるため、Authorization ヘッダーは不要です。これらのURLは非公開として扱ってください。

  • 保存されている元の画像ファイルをバイナリストリームとして返します。
  • 画像は apikey で識別されるデバイスに属している必要があります。
  • Content-Typeは保存ファイルの拡張子に従い、通常は image/jpeg です。

エラー

  • 画像IDが無効、または関係のないものの場合は、404 と { "message": "image not found" } が返ります。
  • 不明なデバイスキーの場合は、500 と { "message": "can not find robot <apikey>" } が返ります。
cURL
curl -L "https://api.kokonna.art/openapi/image/<API_KEY>/123" \
  -o image.jpg

POST/displayImageById

IDで画像を表示

リクエストボディ
{ "imageId": 123 }

{ "success": true } を返します。該当する名前の画像がない場合は、500 と { "message": "image not found" } を返します。

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

名前で画像を表示

リクエストボディ
{ "imageName": "photo.jpg" }

{ "success": true } を返します。該当する名前の画像がない場合は、500 と { "message": "image not found" } を返します。

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

エラー処理

エラー時は、HTTPステータスとJSONの message が返ります。

ステータス 発生する状況 ボディ
404 見つかりません URL内のメソッドが存在しません。 { "message": "can not find method <method_name>" }
429 リクエスト過多 レート制限を超えました。 { "message": "Too many requests, please try again later." }
500 サーバーエラー キーに一致するデバイスがないか、その他のサーバー側のエラーが発生しました。 { "message": "can not find robot <apikey>" } or { "message": "<error_message>" }

ペイロードサイズ

Cloud APIが受け付けるリクエストは最大50 MBです。Base64でのアップロードはこのサイズ内に収めてください。Local APIには独自のアップロード形式と制限があります。