CameraEventImage Schema

Nest Cam (legacy) Nest Hub Max Nest Doorbell (legacy) 

sdm.devices.traits.CameraEventImage

This trait belongs to any device that supports generation of images from events.

Fields

There are no fields available for this trait.

Commands

GenerateImage

Provides a URL to download a camera image from.

This command supports the following events:

Type Element Description
Event Motion event of the CameraMotion trait Motion has been detected by the camera.
Event Person event of the CameraPerson trait A person has been detected by the camera.
Event Sound event of the CameraSound trait Sound has been detected by the camera.
Event Chime event of the DoorbellChime trait The doorbell has been pressed.
Use the eventId from a supported event in the command request to receive a download URL for the camera image related to that event.

GenerateImage request and response

Request

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraEventImage.GenerateImage",
  "params" : {
    "eventId" : "EB-Y7fREK9AeU4yso2PjRrw0HN..."
  }
}

Response

{
  "results" : {
    "url" : "https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "token" : "g.0.eventToken"
  }
}

GenerateImage request fields

Field Description Data Type
eventId ID of the event to request a related camera image for. string
Example: "EB-Y7fREK9AeU4yso2PjRrw0HN..."

GenerateImage response fields

Field Description Data Type
url The URL to download the camera image from. string
Example: "https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1..."
token Token to use in the HTTP Authorization header when downloading the image. string
Example: "g.0.eventToken"

Download a camera image

Make a GET call to the url from a GenerateImage command response, using the token in the HTTP Authorization header with Basic authorization, to download the camera image:

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...

Use width or height query parameters to customize the resolution of the downloaded image. Only one of these parameters need to specified. The other parameter is scaled automatically according to the camera's aspect ratio.

For example, if the camera's aspect ratio is 4:3, to download the camera image with a resolution of 480 x 360 specify either the width or the height:

Width

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?width=480

Height

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?height=360

Other restrictions to the download URL apply:

  • If both parameters are provided in the URL, width is used and height is ignored.
  • If neither parameter is provided in the URL, a default value of 480 is chosen for the width.

See the CameraImage trait for information on image properties.

Errors

The following error code(s) may be returned in relation to this trait:

Error Message RPC Troubleshooting
Camera image is no longer available for download. DEADLINE_EXCEEDED Event images expire 30 seconds after the event is published. Make sure to download the image prior to expiration.
Event id does not belong to the camera. FAILED_PRECONDITION Use the correct eventID returned by the camera event.

See the API Error Code Reference for the full list of API error codes.