Vision Link: Video Understanding and Sharing

What a Persona understands in a video, how she shares videos of her own, and what you must do when a video is problematic.

Overview

Vision Link handles videos in both directions:

• She understands the videos the User sends. She follows what happens in the clip and reacts to it in character.
• She sends videos of her own. When the User asks to see something, she picks a clip from a list you provide.

Both are off by default. You turn them on in each reply request.

Photos work the same way, with their own options and their own price. A few behaviours genuinely differ, and this page points them out as they come. See Vision Link: Photo.

Availability

Chat Model 2.0 and above, for understanding and for sharing alike. See Model Versions.

What Gets Analyzed

Two options on replyParameters.vision, one per direction.

Three rules to know before you report a bug:

• A captioned video is never analyzed. If you set a caption on a shareable video, we use your text and skip the analysis. That clip costs you nothing.
• A reply carries one medium, never two. Photos or videos, not both. If a photo and a video would both fire on the same reply, the photo wins.
• Keep clips small and in MP4. Anything over 5 MB is refused before we finish downloading it. There is no limit on how long a clip runs. MP4 is the only format we handle reliably.

Problematic Videos: Who Does What

Every video a User sends is analyzed. Read this section carefully. Two things catch integrators out: you have to ask for the report, and the report blocks nothing.

What we do

1. We analyze the video.
2. If the analysis flags it as violent, self-harm or illegal content, we withhold the clip from the Persona and send you a chat.video.rejected event on your Incoming Content Endpoint.

The Persona never sees a flagged clip. She answers as if the message had carried no video at all.

Three reasons produce an event, and no others:

Nudity and explicit adult videos are never flagged. Moderation here means violence, self-harm and illegal content, nothing else.

Some clips are dropped with no event at all

When the analysis cannot make out what is in a video, we withhold the clip from the Persona and send you nothing.

From your side it looks like she ignored the clip and answered around it. That is the reason, and there is no signal for it. If a User complains that the Persona did not react to a video, and you received no rejection, this is the most likely explanation.

What the event does not do

Treat chat.video.rejected as an alert that needs a decision from you, never as a block we have already applied on your behalf. Concretely:

• No ban. Nothing on the answer tells you the conversation was interrupted, because it was not.
• Nothing happens to the video or the User. We do not remove the clip, hide it from your platform, or act on the User in any way.

Core Guardian is the one that behaves differently, and the two are easy to mix up. Core Guardian reads the User's text, and it really does stop conversations: it returns a stop reason and a ban duration on the answer. Video analysis never does that.

What you must do

Because nothing is blocked on our side, your own moderation is the only thing that can act on a problematic video. Stopping a User is your decision, and your job.

What we recommend:

1. Receive the event on your incoming content endpoint.
2. Block the conversation temporarily, if you deem it necessary. Stop asking us for replies on that userProfileId and personaProfileId pair. We only write a reply when you ask for one, so not asking is the block. There is nothing to call on our side.
3. Send the video to your own moderation service. The event tells you which message carried the clip (sourceProfileId), so pull the file from your own storage. The URL in the event is ours, not yours, and it is of no use to your moderation team.
4. Apply their decision. Warn, suspend, ban or report the User on your side. If the clip turns out to be fine, start asking us for replies again.

The same split of responsibilities applies to photos. See Problematic Photos: Who Does What.

Pricing

Base cost: €0.03 per analyzed video

You pay once per video file, not per URL.

• We identify a clip by its content, not by its address. The same file behind two different URLs is analyzed once and billed once, across all your conversations and projects.
• An analysis is kept for a year. Unlike photos, Cache-Control is ignored for videos.
• Replacing the file behind a URL is a new clip. Different file, fresh analysis, and you pay again. Same file re-uploaded, nothing to pay.
• A captioned shareable video is never analyzed, so it never costs anything.
• A flagged video costs the same as any other. The analysis is billed first, the moderation check happens after.
• A video we cannot fetch is free. No analysis, no charge, no event.

Analyses appear as their own Video Analyses line item on your pricing page and invoices.

Technical Implementation

Step 1: Use a Supported Model

Send a Chat Model 2.0 or above through replyParameters.chatModel, for example chat-2.1-pro. The dating-* models handle neither video understanding nor video sharing.

Step 2: Enable Video

Switch on the directions you need in replyParameters.vision:

{
  "userProfileId": "xxxx",
  "personaProfileId": "yyyy",
  "replyParameters": {
    "chatModel": "chat-2.1-pro",
    "vision": {
      "sharedVideosAnalysis": true,
      "shareableVideosAnalysis": true
    }
  }
}

Vision settings are read on every request, and any option you leave out counts as false. Send them on every call.

Step 3: Return Video URLs in Your Chat History

In the Chat History Endpoint you host, add a videoUrls array to each message, holding the URLs of the videos attached to that message. It sits alongside pictureUrls and text, and a message can carry any combination of the three.

{
  "messages": [
    {
      "id": "msg_1042",
      "sender": "USER",
      "date": "2026-08-25T10:00:00Z",
      "text": "look what my dog just did",
      "videoUrls": ["https://cdn.example.com/u/1042/dog.mp4"]
    }
  ]
}

Every URL must be publicly reachable at the moment we generate the answer, and HTTPS is strongly recommended. A video is analyzed only if sharedVideosAnalysis is true on that request. Keep clips under 5 MB and in MP4.

Keep the message id meaningful on your side. It is the only thing the rejection event gives you back that you can match.

When the Persona sends a video, it comes back on the answer in message.videoUrls. Check for that property to display it. A reply never carries photos and videos at the same time.

Step 4: Register the Videos She Can Send

List the clips she is allowed to send in replyParameters.shareableVideos. Each entry takes three fields:

How willingly she shares is set by pictureSharingMode, the same setting that governs photos. NORMAL means she shares when asked, EAGER means she shares whenever the conversation invites it. For the full behaviour, read Control Sharing and Sexual Intensity and the Smart Share guide.

To require a video on a specific reply, use forceVideoSharing. Send "true" and we pick the clip that fits best. Send a URL instead and she sends that one. A forced URL that is not in your shareableVideos list gets analyzed on the fly, which costs the usual €0.03.

Your own clips are filtered: if our analysis flags one of them, the Persona never sends it, whether she picked it herself or you forced it. Photos are the exception here — your shareablePictures catalogue is not filtered on a natural share. See the photo guide.

Step 5: Ask for the Event

Open your project's settings and add chat.video.rejected to the list of events sent to your incoming content endpoint. The setup wizard does not offer it, so type it in.

Skip this step and everything else on this page is theory: the video is still analyzed, and you are still billed, but nobody tells you.

Step 6: Handle Rejections and Find the Events Again

Rejections arrive on your Incoming Content Endpoint in this shape:

{
  "event": "chat.video.rejected",
  "data": {
    "projectId": "prj_XXXXXXXXXXXX",
    "sourceProfileId": "msg_1042",
    "videoUrl": "https://cdn.dumgum.com/content-creation/video-analysis/a1b2c3....mp4"
  }
}

The full field reference is on the chat.video.rejected event page. Photos use the same shape under chat.image.rejected, and there the URL is the one you gave us.

How to find a rejection after the fact

1. Log every event as it lands. Store projectId, sourceProfileId and the time you received it. That log is the record you control, and the one your moderation team will work from.
2. Match sourceProfileId to your message. That gives you the conversation, the User, the moment it happened, and your own copy of the clip.
3. Open the Response Explorer to see the conversation around a rejection. Shared videos appear there alongside photos. Look at the reply that followed and the reply parameters that were active. That tells you whether video analysis was on and which model ran.
4. Think the event never reached you? Check first that chat.video.rejected is in your project's event list (Step 5) — that is the usual answer. Then check whether your endpoint was reachable at the time, since these events are not retried. Errors we hit when calling your endpoints show up in the same project logs.
5. Still nothing? Contact support with the projectId, the sourceProfileId and roughly when it happened.

Frequently Asked Questions

Why are we not receiving any rejection events? Almost always because chat.video.rejected is not in your project's event list. It is not there by default and the setup wizard does not offer it. See Step 5. The second cause is an endpoint that was unavailable at the time, since video rejections are not retried.

Do you ban a User who sends an illegal video? No. We send you the event, and that is all. Bans, suspensions and legal reporting are yours.

Are explicit videos rejected? Not by this check. The three reasons above are the only ones. How explicit the Persona gets, and how freely she shares, is set by pictureSharingMode. See Control Sharing and Sexual Intensity.

Does the Persona see a flagged video? No. The clip is withheld from her and she answers as if the message carried no video. This is the opposite of photos, where a flagged photo is still described to her.

Is a flagged video still billed? Yes, €0.03 like any other. We bill the analysis, and the moderation check happens after it.

What is sourceProfileId? Its name is misleading. For a video a User sent, it holds the id of the chat history message that carried the clip, not a profile id. It is the field to match to find the conversation. When the flagged clip is one the Persona was about to send, it does hold her profile id.

Why can't we match the videoUrl in the event? Because it is our address for the file, not yours. Use sourceProfileId.

The Persona ignored a video and we received nothing. Why? Most likely the analysis could not make out what was in the clip. We withhold it from her in that case and send no event. Other candidates: the clip was over 5 MB, the URL was unreachable, or it was not in MP4.

Do you retry the event if our endpoint is down? Not for videos. The event is lost. Photo rejections are retried until your endpoint accepts them.

Is there a size, duration or format limit? 5 MB maximum per clip, no limit on duration, and MP4 only. A clip over the limit is refused before we finish downloading it.

What if a video URL is unreachable when you generate the answer? We ignore the clip as if it had never been sent: no analysis, no charge, no event. The reply is written without it. We also stop trying that URL for a while, so fixing the link and asking for a reply straight away may change nothing. Wait a few minutes.

We re-uploaded a video to the same URL. Is it analyzed again? Only if the file itself changed. We recognise a clip by its content, not by its address. See Pricing.

Why is the Persona offering the same video again? Your id for that clip changed between requests. We track what she has sent by id, so it has to stay stable.

I forced a video and she sent a photo. Why? A reply carries one medium only, and when a photo and a video both resolve, the photo wins. Check whether forcePictureSharing was also set on that request.

She never sends videos at all. Why? Three things to check: a 2.x model in chatModel, shareableVideos is not empty, and shareableVideosAnalysis is on or your clips carry captions. Without either, she does not know what she would be sending.

Does she know what is in the video she sends? Only if you tell her or let us tell her. A caption you provide, or shareableVideosAnalysis, gives her that. With neither, she is sending a clip blind.

Can the Persona send a video we flagged? No. Your own clips are filtered, picked or forced. Photos are the exception: shareablePictures is not filtered on a natural share.

Where do the videos she sends come back? On the answer, in message.videoUrls. See the Answer reference.

Is it the same for photos? Same design, separate options, separate price, and several behaviours genuinely differ. See Vision Link: Photo.