Raw HTTP Quickstart

Use this guide when you want direct HTTP examples. If you are building in Node.js or Bun, start with Node.js SDK quickstart instead.

1. Create an upload target

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": 12345678
  }'

Upload the file bytes to the returned uploadUrl.

2. Create a project

curl -X POST https://api.youka.io/api/v1/projects \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: create-project-song-1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Artist - Song",
    "inputFileId": "file_123",
    "lyricsSource": {
      "type": "align",
      "lyrics": "First line\nSecond line\n...",
      "syncModel": "musicai-alignment",
      "language": "en"
    },
    "splitModel": "mdx23c"
  }'

3. Poll the task

curl https://api.youka.io/api/v1/tasks/task_123 \
  -H "Authorization: Bearer yk_..."

When the task is terminal, its output contains the key result IDs for the operation.

4. Read project state

curl https://api.youka.io/api/v1/projects/proj_123 \
  -H "Authorization: Bearer yk_..."

This returns the long-lived project state, including stems, alignments, exports, and the active project settings.

5. Create an export

curl -X POST https://api.youka.io/api/v1/projects/proj_123/exports \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: export-song-1" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "1080p",
    "quality": "high"
  }'

Then poll the returned task or read the export directly:

curl https://api.youka.io/api/v1/exports/export_123 \
  -H "Authorization: Bearer yk_..."