<br />

# CameraEventImage Schema

[Nest Cam (legacy)](https://developers.google.com/nest/device-access/api/camera.md.txt) [Nest Hub Max](https://developers.google.com/nest/device-access/api/display.md.txt) [Nest Doorbell (legacy)](https://developers.google.com/nest/device-access/api/doorbell.md.txt)

`sdm.devices.traits.CameraEventImage`

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

<br />

## Fields


There are no fields available for this trait.

<br />

## Commands

<br />

### GenerateImage

Provides a URL to download a camera image from.

This command supports the following events:

| Type | Element | Description |
|---|---|---|
| Event | [Motion](https://developers.google.com/nest/device-access/traits/device/camera-motion.md.txt#motion) event of the CameraMotion trait | Motion has been detected by the camera. |
| Event | [Person](https://developers.google.com/nest/device-access/traits/device/camera-person.md.txt#person) event of the CameraPerson trait | A person has been detected by the camera. |
| Event | [Sound](https://developers.google.com/nest/device-access/traits/device/camera-sound.md.txt#sound) event of the CameraSound trait | Sound has been detected by the camera. |
| Event | [Chime](https://developers.google.com/nest/device-access/traits/device/doorbell-chime.md.txt#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.

<br />

> [!NOTE]
> Event images expire 30 seconds after the event is published. Make sure to download the image prior to expiration.

#### GenerateImage request and response

### Request

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

### 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: "HHtcFIhuvVkASGKokgtK5rJhrQ..." |

#### GenerateImage response fields

| Field | Description | Data Type |
|---|---|---|
| `url` | The URL to download the camera image from. | `string` Example: "https://<var translate="no">domain</var>/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1..." |
| `token` | Token to use in the HTTP Authorization header when downloading the image. | `string` Example: "g.0.eventToken" |

<br />

## Download a camera image

Make a GET call to the `url` from a
[GenerateImage](https://developers.google.com/nest/device-access/traits/device/camera-event-image.md.txt#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](https://developers.google.com/nest/device-access/traits/device/camera-image.md.txt) 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](https://developers.google.com/nest/device-access/reference/errors/api.md.txt) for
the full list of API error codes.

<br />