> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Editor Project

> Start a video editing project from videos you uploaded, ready for cutting.

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](/api-reference/upload-file) and finalize them; only
finalized video files are accepted. Then cut the project with
[Apply Editor Ops](/api-reference/apply-editor-ops) and export it with
[Render Editor Project](/api-reference/render-editor-project). To add more videos to the project
later, use [Add Editor Files](/api-reference/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

<ParamField body="file_ids" type="string[] (UUID)" required>
  1 to 20 finalized video file ids, in the order they should play.
</ParamField>

<ParamField body="title" type="string">
  Optional project title (up to 200 characters).
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Optional output aspect ratio: `9:16`, `1:1`, or `4:5`.
</ParamField>

## Response

Returns `201` with the project, in the same shape as
[Get Editor Project](/api-reference/get-editor-project): `project_id`, `title`, `aspect_ratio`,
`duration_ms`, `updated_at`, `assets`, `clips`, `render`, and `editor_url`.

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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,
      "editor_url": "https://www.genviral.io/editor/b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f?workspace=personal"
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 invalid_json` - request body is not valid JSON
* `400 invalid_request` - `Idempotency-Key` header is missing or longer than 255 characters
* `401` - 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 video
* `409 idempotency_key_reused` - this `Idempotency-Key` was already used with a different body
* `409 request_in_progress` - an identical request with this key is still being processed; retry shortly
* `422 invalid_payload` - body failed validation (see `issues`)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.