Skip to main content
POST
/
annotations
/
annotations
/
v1
cURL
curl --request POST \
  --url https://api.mottostreaming.com/annotations/annotations/v1 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "<string>",
  "type_id": "<string>",
  "video_id": "<string>",
  "offset": "<string>",
  "visibility": "VISIBILITY_UNSPECIFIED",
  "event_id": "<string>",
  "creative_work_id": "<string>",
  "entity_ids": [
    "<string>"
  ],
  "action_overrides": {},
  "start_offset": "<string>",
  "end_offset": "<string>",
  "source_type": "SOURCE_TYPE_UNSPECIFIED",
  "source_id": "<string>",
  "confidence": 123,
  "timer_label": "<string>",
  "order": "<string>"
}
'
{
  "annotation": {
    "project_id": "<string>",
    "type_id": "<string>",
    "video_id": "<string>",
    "offset": "<string>",
    "id": "<string>",
    "visibility": "VISIBILITY_UNSPECIFIED",
    "event_id": "<string>",
    "creative_work_id": "<string>",
    "entity_ids": [
      "<string>"
    ],
    "action_overrides": {},
    "start_offset": "<string>",
    "end_offset": "<string>",
    "source_type": "SOURCE_TYPE_UNSPECIFIED",
    "source_id": "<string>",
    "confidence": 123,
    "timer_label": "<string>",
    "order": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json

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.

​
project_id
string
required
​
type_id
string
required

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

​
video_id
string
required

The video in which this annotation occurs.

​
offset
string
required

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.

If the offset is not know, you can provide a negative value, e.g. -1. Note: if you provide a negative offset, the annotation may be ignored by some systems that require a known offset, like annotation actions (e.g. clipping a video).

See also: start_offset and end_offset.

​
visibility
enum<string>

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.

Available options:
VISIBILITY_UNSPECIFIED,
VISIBILITY_PUBLISHED,
VISIBILITY_UNLISTED,
VISIBILITY_HIDDEN
​
event_id
string

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).

​
creative_work_id
string

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).

​
entity_ids
string[]

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.

​
action_overrides
object

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.

​
start_offset
string

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.

​
end_offset
string

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.

​
source_type
enum<string>

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

Available options:
SOURCE_TYPE_UNSPECIFIED,
SOURCE_TYPE_MANUAL,
SOURCE_TYPE_AI,
SOURCE_TYPE_EXTERNAL,
SOURCE_TYPE_CROWD
​
source_id
string

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

​
confidence
number<float>

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.

​
timer_label
string

A textual representation of the scoreboard's time value at the time of the annotation. This can be any representation that you choose, and may be used to display the time of the annotation to end users in a more human-readable format. This differs from the offset field, which is a time value relative to the start of the video. This is an optional field. Example's for soccer: 46' (46th minute), 90+3' (90th minute, 3 minutes of added time).

​
order
string

An integer that can be used to order annotations of the same type within a video. It is advised to space this out in large increments (e.g. 1000) to allow for future insertions and re-orderings. If this field is not set, it will take the value of the offset field.

Response

OK

​
annotation
object

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.