curl --request POST \
--url https://www.genviral.io/api/partner/v1/editor/projects \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 3f7c1a52-8d0e-4b66-a1c3-9e2d5b7f0a41' \
--data '{
"file_ids": ["8c2f5a1e-6b7d-4e3a-9f10-2d4c6b8a0e12"],
"title": "Launch cut",
"aspect_ratio": "9:16"
}'
{
"ok": true,
"code": 201,
"message": "Editor project created",
"data": {
"project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
"title": "Launch cut",
"aspect_ratio": "9:16",
"duration_ms": 42000,
"updated_at": "2026-10-02T12:00:00.000Z",
"assets": [
{
"asset_id": "asset_1",
"name": "interview.mp4",
"url": "https://example.com/interview.mp4",
"poster_url": null,
"duration_ms": 42000
}
],
"clips": [
{
"clip_id": "clip_1",
"asset_id": "asset_1",
"start_ms": 0,
"end_ms": 42000,
"source_start_ms": 0,
"source_end_ms": 42000,
"lane": 0
}
],
"render": null
}
}
Video Editor
Create Editor Project
Start a video editing project from videos you uploaded, ready for cutting.
POST
/
api
/
partner
/
v1
/
editor
/
projects
curl --request POST \
--url https://www.genviral.io/api/partner/v1/editor/projects \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 3f7c1a52-8d0e-4b66-a1c3-9e2d5b7f0a41' \
--data '{
"file_ids": ["8c2f5a1e-6b7d-4e3a-9f10-2d4c6b8a0e12"],
"title": "Launch cut",
"aspect_ratio": "9:16"
}'
{
"ok": true,
"code": 201,
"message": "Editor project created",
"data": {
"project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
"title": "Launch cut",
"aspect_ratio": "9:16",
"duration_ms": 42000,
"updated_at": "2026-10-02T12:00:00.000Z",
"assets": [
{
"asset_id": "asset_1",
"name": "interview.mp4",
"url": "https://example.com/interview.mp4",
"poster_url": null,
"duration_ms": 42000
}
],
"clips": [
{
"clip_id": "clip_1",
"asset_id": "asset_1",
"start_ms": 0,
"end_ms": 42000,
"source_start_ms": 0,
"source_end_ms": 42000,
"lane": 0
}
],
"render": null
}
}
Creates a video editor project in the authenticated key scope from one or more finalized video
files. The files are laid back to back in the order you give. The project then shows up in the
Genviral web editor as well, so a person can pick it up where your agent left off.
Upload videos first with Upload File and finalize them; only
finalized video files are accepted. Then cut the project with
Apply Editor Ops and export it with
Render Editor Project. To add more videos to the project
later, use Add Editor Files.
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 original project and never creates a second one.
- Reusing a key with a different body returns
409 idempotency_key_reused. - A request that is refused does not consume its key, so you can fix the problem and retry.
Body Parameters
string[] (UUID)
required
1 to 20 finalized video file ids, in the order they should play.
string
Optional project title (up to 200 characters).
string
Optional output aspect ratio:
9:16, 1:1, or 4:5.Response
Returns201 with the project, in the same shape as
Get Editor Project: project_id, title, aspect_ratio,
duration_ms, updated_at, assets, clips, and render.
curl --request POST \
--url https://www.genviral.io/api/partner/v1/editor/projects \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 3f7c1a52-8d0e-4b66-a1c3-9e2d5b7f0a41' \
--data '{
"file_ids": ["8c2f5a1e-6b7d-4e3a-9f10-2d4c6b8a0e12"],
"title": "Launch cut",
"aspect_ratio": "9:16"
}'
{
"ok": true,
"code": 201,
"message": "Editor project created",
"data": {
"project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
"title": "Launch cut",
"aspect_ratio": "9:16",
"duration_ms": 42000,
"updated_at": "2026-10-02T12:00:00.000Z",
"assets": [
{
"asset_id": "asset_1",
"name": "interview.mp4",
"url": "https://example.com/interview.mp4",
"poster_url": null,
"duration_ms": 42000
}
],
"clips": [
{
"clip_id": "clip_1",
"asset_id": "asset_1",
"start_ms": 0,
"end_ms": 42000,
"source_start_ms": 0,
"source_end_ms": 42000,
"lane": 0
}
],
"render": null
}
}
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 file_not_found- a file does not exist in the key scope, is not finalized, or is not a video409 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)