How do you post and share a video within a group using the Post Video API?

Who is this for and why it matters

Use this API when you want to programmatically upload and share videos inside a group (loop) within your Community Media Network.

This matters because:

Video replies are the core engagement layer inside groups
It enables real-time content participation via integrations
It powers UGC (user-generated content) and creator-led conversations

If you're building interactive experiences, creator workflows, or automated content pipelines, this API is essential.

What does the Post Video API do?

The Post Video API allows you to:

Upload and post a video reply inside a group (chat/loop)
Attach metadata like resolution, duration, and aspect ratio
Add descriptions with mentions (users/communities)
Associate questions with the video to drive engagement

It essentially powers video-based conversations within groups.

API Details

URL: /api/thirdparty/conversation/reply
Method: POST
Authentication Required: Yes (Bearer Token)
Mandatory Fields: chat_id, aspect_ratio, duration, link, resolution, size, video_name, thumbnail_name

Before you begin

1. Authenticate your request

Generate a gn-access-token using the Authentication API.

Pass it in the header: Authorization - Bearer <gn-access-token>

2. Ensure group (chat) exists

You must have a valid chat_id (group identifier) where the video will be posted.

Request Structure

Request Body

{
  "aspect_ratio": "16:9",
  "duration": "8",
  "link": "",
  "resolution": "688x1220",
  "size": "5",
  "chat_id": "1a14b9e2-9552-48d5-b1e3-a1ba237891cf",
  "video_name": "917016535860_15954965.mp4",
  "thumbnail_name": "917016535860_15954965.jpg",
  "description_text": "hi this is @hg and i like community abc",
  "description_data": "[\"hithisis\",{\"user_id\":\"355c0856-9d99-4286-a3e0-fc5164b77861\"},\"andilikecommunity\",{\"community_id\":\"fe3bdd3b-1fcb-44f3-a7ac-15b59796b6f9\"}]",
  "questions": [
    "1305faddc8000a5b",
    "1305f96cac800a5a"
  ],
  "is_ai_generated": false,
  "message_id": "d282b66a-9c3d-4712-b0d5-1c698d923dec",
  "video_path": "trends_videos/2024/5/6/genuin",
  "thumbnail_path": "trends_thumbnail/2024/5/6/genuin",
  "is_ai_generated_video": true,
  "is_ai_generated_thumbnail": true
}

Field-level understanding

Core Video Fields

chat_id - Group where the video will be posted
video_name / thumbnail_name - Media file references
video_path / thumbnail_path - Storage location
duration / size / resolution / aspect_ratio - Video metadata

Content & Engagement Layer

description_text - Human-readable caption
description_data - Structured mentions (users/communities)
questions - Attach questions to drive responses and interaction

AI & Control Flags

is_ai_generated - Whether content is AI-generated
is_ai_generated_video/thumbnail - AI-assisted media creation

Message Identification

message_id - Unique identifier for the video message

What happens on success?

Success Condition

If all inputs are valid:

Video is successfully posted inside the group
It becomes part of the conversation thread
Engagement tracking begins (views, replies, etc.)

Response Code: 200 OK

Response Highlights

{
  "chat_id": "1a14b9e2-9552-48d5-b1e3-a1ba237891cf",
  "share_url": "https://app.qa.begenuin.com/l/11d88992ba811475",
  "chats": [
    {
      "conversation_id": "a5006e51-8950-4e1f-9b9a-65714720b0a6",
      "video_url": "...",
      "thumbnail_url": "...",
      "share_url": "https://app.qa.begenuin.com/v/..."
    }
  ]
}

Important

conversation_id - Unique identifier for the posted video
share_url (inside chats) - Direct link to access the video

Example format:

https://app.qa.begenuin.com/v/{video_id}?l={loop_id}

Error Handling

1. Bad Request

Condition: Invalid or incomplete request payload

Response Code: 400 Bad Request

Response Body: {}

2. Internal Server Error

Condition:

Duplicate reply attempt
Server-side validation failure

Response Code: 500 Internal Server Error

Response Body:

{
  "code": "5057",
  "message": "You have already replied to this video.",
  "data": {}
}

Best Practices

Ensure chat_id is valid before posting
Maintain correct video metadata (aspect ratio, resolution, duration)
Use questions strategically to drive engagement
Validate media paths and file names before submission
Avoid duplicate replies for the same context
Use AI-generated flags for faster content workflows when needed

What to do next

Once the video is posted:

Share the share_url to drive engagement
Track views, replies, and interactions
Chain responses to build loop-based conversations
Integrate with monetization or campaigns