curl --request POST \
--url https://www.genviral.io/api/partner/v1/editor/projects/b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 5a1c9e72-0d4b-4f3a-9b6e-7c2d1e8f4a90' \
--data '{
"text": "IMG_8103 has 17 s of sky after the phone tipped over. Cutting that first."
}'
{
"ok": true,
"code": 201,
"message": "Editor message posted",
"data": {
"project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
"posted_at": "2026-10-02T12:04:12.000Z"
}
}
Video Editor
Post Editor Message
Show a short message to the user watching a video project in the Genviral editor.
POST
/
api
/
partner
/
v1
/
editor
/
projects
/
{projectId}
/
messages
curl --request POST \
--url https://www.genviral.io/api/partner/v1/editor/projects/b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 5a1c9e72-0d4b-4f3a-9b6e-7c2d1e8f4a90' \
--data '{
"text": "IMG_8103 has 17 s of sky after the phone tipped over. Cutting that first."
}'
{
"ok": true,
"code": 201,
"message": "Editor message posted",
"data": {
"project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
"posted_at": "2026-10-02T12:04:12.000Z"
}
}
Posts a short message to the open Genviral web editor, where it appears live beside the timeline
together with each edit’s step note. Use it to narrate your work as it happens: what you are about
to do, what you found (for example which clip and which seconds), what the next edit will change,
and a closing summary.
A message is narration only. It never changes the project, and its
updated_at stays the same, so
the expected_updated_at you pass to your next Apply Editor Ops
call remains valid and the open editor does not reload.
Messages are labelled in the editor with who sent them (Claude, ChatGPT, another MCP client, or
the API), derived from the credential. The editor keeps the newest 60 entries of a project’s
activity.
Idempotency
Idempotency-Key is required and is scoped to the API key (or MCP grant) that sends it.
- Retrying with the same key and the same body returns the first
posted_atand shows the message once. - Reusing a key with a different body returns
409 idempotency_key_reused.
Rate Limits
Messages are rate limited per account owner (120 per hour across all keys and workspaces). Over the limit the request is refused with429 rate_limited and a retry_after_seconds.
Path Parameters
string (UUID)
required
The project id.
Body Parameters
string
required
1 to 600 characters of plain text, trimmed. Line breaks are allowed; other control characters
and markdown formatting are not meant for this field. Keep it to 1-3 conversational sentences in
the user’s language.
Response
Returns201 with the project id and when the message was posted.
curl --request POST \
--url https://www.genviral.io/api/partner/v1/editor/projects/b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f/messages \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 5a1c9e72-0d4b-4f3a-9b6e-7c2d1e8f4a90' \
--data '{
"text": "IMG_8103 has 17 s of sky after the phone tipped over. Cutting that first."
}'
{
"ok": true,
"code": 201,
"message": "Editor message posted",
"data": {
"project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
"posted_at": "2026-10-02T12:04:12.000Z"
}
}
Error Responses
400 invalid_json- request body is not valid JSON400 invalid_request-Idempotency-Keyheader is missing or longer than 255 characters401- authentication failed (missing/invalid/revoked token)404 project_not_found- the project does not exist in the key scope409 idempotency_key_reused- thisIdempotency-Keywas already used with a different body409 request_in_progress- an identical request with this key is still being processed; retry shortly422 invalid_payload- body failed validation (seeissues)429 rate_limited- the hourly message allowance is spent; retry afterretry_after_seconds503 provider_unavailable- the rate limiter could not answer; retry shortly