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" : "cZdUoE1G3AqS8rGcqwU2KNOlu7..."
  }
}

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: "cZdUoE1G3AqS8rGcqwU2KNOlu7..."

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.