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

# Projects

> Upload source media and create, quote, inspect, update, list, and delete karaoke projects

A project is the work-in-progress resource for one karaoke track. It owns the
source media, synced lyrics, separated stems, render settings, and exports.

## Endpoints

| Method   | Path                          | Purpose                                                    |
| -------- | ----------------------------- | ---------------------------------------------------------- |
| `POST`   | `/uploads`                    | Allocate a signed upload URL for source media.             |
| `GET`    | `/projects`                   | List projects owned by the account.                        |
| `POST`   | `/projects`                   | Create a project from an uploaded input file.              |
| `POST`   | `/projects/quote`             | Quote the credits required to create a project.            |
| `GET`    | `/projects/{projectId}`       | Fetch a project with stems, lyrics, exports, and settings. |
| `PATCH`  | `/projects/{projectId}`       | Patch project metadata such as title or artists.           |
| `DELETE` | `/projects/{projectId}`       | Delete a project and its associated artifacts.             |
| `GET`    | `/projects/{projectId}/tasks` | List task history for a project.                           |

Full request and response schemas are in **API reference**.

## Upload a source file

```bash theme={null}
curl -X POST https://api.youka.io/api/v1/uploads \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "song.mp3",
    "contentType": "audio/mpeg",
    "contentLength": 4521344
  }'
```

The response includes `inputFileId` and `uploadUrl`. Upload the bytes to
`uploadUrl`, then use `inputFileId` in project creation or quote requests.

## Quote a project

```bash theme={null}
curl -X POST https://api.youka.io/api/v1/projects/quote \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputFileId": "file_abc123",
    "lyricsSource": { "type": "transcribe", "language": "en" },
    "splitModel": "mdx23c"
  }'
```

If you already know the duration, pass `durationSeconds` instead of
`inputFileId` to quote without uploading.

## Create a project

```bash theme={null}
curl -X POST https://api.youka.io/api/v1/projects \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-song-123" \
  -d '{
    "title": "My Song",
    "inputFileId": "file_abc123",
    "lyricsSource": { "type": "transcribe", "language": "en" },
    "splitModel": "mdx23c"
  }'
```

Project creation is async. The response includes `projectId`, `taskId`,
`projectUrl`, and `taskUrl`. Poll [tasks](/en/api/tasks) or fetch the project
until the latest task reaches a terminal state.

## Inspect and update

```bash theme={null}
curl https://api.youka.io/api/v1/projects/prj_abc123 \
  -H "Authorization: Bearer yk_..."
```

```bash theme={null}
curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated title",
    "artists": ["Artist name"]
  }'
```

`PATCH` requires at least one of `title` or `artists`.

## List and delete

```bash theme={null}
curl https://api.youka.io/api/v1/projects \
  -H "Authorization: Bearer yk_..."
```

```bash theme={null}
curl -X DELETE https://api.youka.io/api/v1/projects/prj_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-prj_abc123"
```

<Warning>
  Project deletion is permanent. Use an idempotency key so retries are safe.
</Warning>

## Project tasks

```bash theme={null}
curl https://api.youka.io/api/v1/projects/prj_abc123/tasks \
  -H "Authorization: Bearer yk_..."
```

This returns the project task history, including project creation, lyric sync,
stem separation, and export tasks.

## What's next

* [Lyrics sync](/en/api/lyrics-sync) - re-run transcription or alignment
* [Stems](/en/api/stems) - re-run stem separation
* [Project settings](/en/api/project-settings) - read and patch active settings
* [Exports](/en/api/exports) - render a finished video