# Start a remake

> Start a remake of your own video: Raylight makes a blank project (one empty shot at the source's nearest aspect ratio and frame rate) in your personal workspace's Remakes folder and answers with the remake. The project is held from the moment it exists: only the builder tab and your CLI's uploads may change it until the remake ends. `rightsAttested` must be true: you confirm you own the video or have the right to use it, and the answer is stored with the remake. Free; one remake runs at a time, five a day, sources up to 3 minutes and within your plan's video limits. `npx raylight video-to-project <video>` does all of this for you.

### POST /v1/remakes

**Start a remake**

Start a remake of your own video: Raylight makes a blank project (one empty shot at the source's nearest aspect ratio and frame rate) in your personal workspace's Remakes folder and answers with the remake. The project is held from the moment it exists: only the builder tab and your CLI's uploads may change it until the remake ends. `rightsAttested` must be true: you confirm you own the video or have the right to use it, and the answer is stored with the remake. Free; one remake runs at a time, five a day, sources up to 3 minutes and within your plan's video limits. `npx raylight video-to-project <video>` does all of this for you.

Auth: `Authorization: Bearer rl_live_...` with the `remake` scope.

Request body (application/json):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fileName` | string | yes |  |
| `bytes` | integer | yes |  |
| `durationMs` | integer | yes |  |
| `width` | integer | yes |  |
| `height` | integer | yes |  |
| `fps` | number | yes |  |
| `sha256` | string | yes |  |
| `mime` | enum | no | One of: `video/mp4`, `video/quicktime`, `video/webm`. |
| `rightsAttested` | enum | yes |  |
| `agent` | enum | yes | One of: `claude`, `codex`. |
| `cliVersion` | string | yes |  |

Responses:

| Status | Meaning |
| --- | --- |
| 201 | The new remake. |
| 400 | Invalid request. |
| 401 | Missing, invalid or revoked key. |
| 403 | The key lacks the scope, or the key's owner has view-only access to the workspace (code `forbidden`). |
| 404 | Not found. |
| 409 | Another remake of yours is still running (code `remake_running`). |
| 429 | Rate limited, or a monthly cap reached. |

Response body (201):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `remake` | object | yes |  |
| `remake.id` | uuid | yes |  |
| `remake.status` | enum | yes | The furthest stage reached: studying (the study runs on your machine), building (shots land in the project as they are built; overlaps studying), polishing (the film-wide pass), needs_repair (the CLI is running the repair session), then done, failed or canceled. New values may be added; treat unknown ones as opaque. One of: `studying`, `building`, `polishing`, `needs_repair`, `done`, `failed`, `canceled`. |
| `remake.projectId` | uuid \| null | yes |  |
| `remake.projectUrl` | url \| null | yes |  |
| `remake.shots` | object[] | yes |  |
| `remake.shots[].index` | integer | yes |  |
| `remake.shots[].startMs` | number | yes |  |
| `remake.shots[].durationMs` | number | yes |  |
| `remake.shots[].state` | enum | yes | One of: `skeleton`, `building`, `built`, `failed`. |
| `remake.repair` | object \| null | yes |  |
| `remake.repair.requested` | boolean | yes |  |
| `remake.repair.uncovered` | object[] | yes |  |
| `remake.repair.uncovered[].segmentId` | string | yes |  |
| `remake.repair.uncovered[].firstMs` | number | yes |  |
| `remake.repair.uncovered[].lastMs` | number | yes |  |
| `remake.repair.uncovered[].box` | object | yes |  |
| `remake.repair.uncovered[].box.x` | number | yes |  |
| `remake.repair.uncovered[].box.y` | number | yes |  |
| `remake.repair.uncovered[].box.w` | number | yes |  |
| `remake.repair.uncovered[].box.h` | number | yes |  |
| `remake.repair.uncovered[].samples` | integer | yes |  |
| `remake.report` | object \| null | yes |  |
| `remake.report.glitches` | any[] | yes |  |
| `remake.report.gaps` | any[] | yes |  |
| `remake.report.notes` | string[] | yes |  |
| `remake.error` | string \| null | yes |  |
| `remake.errorCode` | enum \| null | yes | One of: `cli_stopped`, `tab_lost`, `study_error`, `build_error`. |
| `remake.libraryEligible` | boolean | yes | Whether this remake (the video, the study and the plan applied) may feed Raylight's motion library. False once the owner or the workspace turns data sharing off (Settings, Improve Raylight); that switch is the only opt-out. |
| `remake.source` | object | yes |  |
| `remake.source.fileName` | string | yes |  |
| `remake.source.durationMs` | integer | yes |  |
| `remake.source.width` | integer | yes |  |
| `remake.source.height` | integer | yes |  |
| `remake.source.fps` | number | yes |  |
| `remake.agent` | enum | yes | One of: `claude`, `codex`. |
| `remake.builder` | object | yes |  |
| `remake.builder.attached` | boolean | yes |  |
| `remake.builder.lastSeenAt` | string \| null | yes |  |
| `remake.createdAt` | string | yes |  |
| `remake.updatedAt` | string | yes |  |

Example (curl):

```bash
curl -X POST https://api.raylight.app/v1/remakes \
  -H "Authorization: Bearer $RAYLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "<fileName>",
  "bytes": 1,
  "durationMs": 1,
  "width": 1,
  "height": 1,
  "fps": 1,
  "sha256": "<sha256>",
  "rightsAttested": true,
  "agent": "claude",
  "cliVersion": "<cliVersion>"
}'
```

## More

- Previous: [List your remakes](https://www.raylight.app/docs/reference/get-v1-remakes.md)
- Next: [Read a remake](https://www.raylight.app/docs/reference/get-v1-remakes-id.md)
- All docs: https://www.raylight.app/llms.txt
- Everything in one file: https://www.raylight.app/llms-full.txt
- OpenAPI: https://api.raylight.app/v1/openapi.json