---
title: "Create a task"
method: POST
path: "/api/v1/task"
tags: ["Tasks"]
---

# Create a task

`POST /api/v1/task`

Submit a music, lyrics, upload, or concat task. Returns immediately with
a `task_id`; poll `GET /api/v1/task/{taskId}` for completion.
Credits are frozen at submission and either settled on success or refunded on failure.
Input is validated before any credits, task record, or upstream-provider
side effect. Task creation does not currently support idempotency keys;
treat an uncertain network or `5xx` outcome as unknown rather than
automatically submitting the same payload again.

## Request body

- TaskCreateRequest — unresolved $ref

## Response `202`

Task accepted, pending processing

- TaskSubmitResponse
  - `code` 202, required
  - `data` TaskSubmitData, required
    - `task_id` string, uuid, required — The task's unique id. Use with `GET /api/v1/task/{taskId}` to poll.
    - `type` 'music' | 'lyrics' | 'upload' | 'concat', required
    - `status` 'pending', required — Initial state is always `pending`.
    - `credits_charged` integer, required — Credits frozen from the balance for this task.
    - `created_at` string, date-time, required

## Other responses

- `400` — Request body missing required fields or contains invalid values.
- `401` — Missing or invalid API key.
- `402` — Balance does not cover this task's credit cost.
- `403` — The authenticated account is not allowed to create this task.
- `429` — Rate limit exceeded. Default quota is 120 requests per 60 seconds per API key.
- `500` — Unexpected server error. Retry only when the operation is known to be safe; task creation may have an ambiguous outcome until idempotency support is available.
- `502` — Upstream AI provider returned an error. For task creation, do not blindly retry an ambiguous 502 without an idempotency key.

## Changes

> 3 revisions in range; 1 could not be searched.

- **2026-08-06** `1c23fd441ed1` — 5 breaking, 10 info
  - removed the required property `created_at` from the response with the `202` status
  - removed the required property `credits_charged` from the response with the `202` status
  - removed the required property `status` from the response with the `202` status
  - removed the required property `task_id` from the response with the `202` status
  - …11 more

[Change history](https://skmtc.dev/sunor/apis/sunor-api/changes/api/v1/task/post.md)

---

[API](https://skmtc.dev/sunor/apis/sunor-api.md) · [All operations](https://skmtc.dev/sunor/apis/sunor-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sunor/sunor-api/revisions/59314c3f36f7/schema)