Create annotation

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

The type of annotation. This corresponds to a set of previously defined types.

The video in which this annotation occurs.

The time at which this annotation occurs in the video. This is defined in milliseconds, relative to the start of the video. For example, if a goal happens after 5 minutes of the video, this would be 300000.

See also: start_offset and end_offset.

The visibility of the annotation. If the annotation is hidden, then it will not be shown to the user. Note: depending on the configuration of the annotation type, some of the actions associated with this annotation may still have publicly visible consequences (e.g. a generated clip may be visible to the public, if so configured).

This may be left to unspecified, in which case the visibility will be inherited from the annotation type.

Optional. When provided, this should be an event ID that is associated with this annotation. This information can be provided by downstream services that need more context, or to perform associated actions (e.g. updating event metadata).

Optional. When provided, this should be an creative work ID that is associated with this annotation. This information can be provided by downstream services that need more context, or to perform associated actions (e.g. updating creative work metadata).

Optional. When provided, this should be a list of entity IDs that are associated with this annotation. This information can be provided by downstream services that need more context, or to perform associated actions. The kinds of entities that should be associated with an annotation are defined by the annotation type.

A map that can be used to override action configurations for this specific annotation.

For example, let's assume there are two action types configured on the associated annotation type, create_clip and share_to_instagram. The existing action configuration for create_clip may look like this:

{
  "create_clip": {
    "name": "Goal",
    "relative_end_offset": 10000,
    "relative_start_offset": -10000
  }
}

This would result in a clip with a 20 second duration, starting 10 seconds before the annotation and ending 10 seconds after. However, if you are creating an annotation for a goal that you know took more (or less) time to fully capture, you can override the action configuration for this specific annotation:

{
  "create_clip": {
    "relative_end_offset": 13000,
    "relative_start_offset": -15000
  }
}

You can also override multiple action configurations at once:

{
  "create_clip": {
    "relative_end_offset": 13000,
    "relative_start_offset": -15000
  },
  "share_to_instagram": {
    "social_media_post": "What a beauty! #goal #soccer"
  }
}

The structure of this object should match the structure of the action_configuration's configuration property, but you do not have to provide all values. Any values you do not provide will be taken from the existing action configuration.

The time at which the relevant portion of the annotation occurs in the video. This is defined in milliseconds, relative to the start of the video. For example, if a goal happens after 5 minutes of the video, but the action starts at 4 minutes and 50 seconds, this would be 290000.

Providing this can be useful for annotation actions that work with ranges, e.g. creating a clip that starts before the annotation. This is an optional value, and when not provided, the start_offset will be derived from offset based on the action configuration.

The time at which the relevant portion of the annotation ends in the video. This is defined in milliseconds, relative to the start of the video. For example, if a goal happens after 5 minutes of the video, but the action ends at 5 minutes and 10 seconds, this would be 310000.

Providing this can be useful for annotation actions that work with ranges, e.g. creating a clip that ends after the annotation. This is an optional value, and when not provided, the end_offset will be derived from offset based on the action configuration.

The source of the annotation. This can be used to track where the annotation came from.

A unique identifier for the source of the annotation. This can be used to track where the annotation came from. Optional.

The confidence score of the annotation, meaning how certain it is that this annotation is accurate. This is a floating point number between 0 and 1, where 0 means no confidence and 1 means full confidence.

Annotation is an invocation of an annotation type and represents a single moment in a video that represents an occurrence of that annotation type. For example, if you have an annotation type "goal", then an Annotation could created when a goal occurs in the video.