> ## Documentation Index
> Fetch the complete documentation index at: https://developer.audioshake.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Task
Submit a media source and up to 20 model targets for processing. Each target specifies a [model](/models) and output format.
Provide exactly one source — either a public `url` or an `assetId` from a [previous upload](/api-reference/assets/upload).
To write outputs directly to your own S3 bucket, see [Custom S3 Write Destination](/api-reference/custom-storage).
## Examples
**Separate vocals and instrumental:**
```json theme={null}
{
"assetId": "your_asset_id",
"targets": [
{ "model": "vocals", "formats": ["wav"] },
{ "model": "instrumental", "formats": ["wav"] }
]
}
```
**Transcribe lyrics:**
```json theme={null}
{
"assetId": "your_asset_id",
"targets": [
{ "model": "transcription", "formats": ["json"] }
]
}
```
## Checking results
Tasks process asynchronously. The response returns a Task `id` you can use to check progress:
Each target begins in `processing` status.
Call [Get Task by ID](/api-reference/tasks/get) and check each target's `status`. When a target finishes, its status becomes `completed` (with output download links) or `error`.
Use [webhooks](/api-reference/tasks/webhooks) to get notified when a Task completes instead of polling.
## OpenAPI
````yaml POST /tasks
openapi: 3.1.0
info:
title: AudioShake API
version: 1.0.0
description: >-
API for AI-powered audio source separation, stem extraction, and
transcription.
license:
name: Proprietary
url: https://www.audioshake.ai/terms
contact:
name: AudioShake
url: https://audioshake.ai
servers:
- url: https://api.audioshake.ai
security:
- apiKey: []
tags:
- name: assets
description: Audio and media file assets managed by AudioShake
- name: tasks
description: Stem separation, source separation, and transcription alignment tasks
paths:
/tasks:
post:
tags:
- tasks
summary: Create Task
operationId: createTask
requestBody:
content:
application/json:
schema:
oneOf:
- additionalProperties: false
type: object
properties:
assetId:
description: Asset ID of an input media file
type: string
writeDestination:
description: >-
Optional. S3 URI prefix to write outputs under (e.g.
"s3://my-bucket/outputs"). The bucket must be covered by
a configured storage integration. Outputs are organized
as
//targets//output/.
See Custom S3 Write Destination.
format: uri
type: string
metadata:
description: >-
Client-provided metadata. Stored and returned as-is in
responses and webhooks.
maxLength: 4096
type: string
targets:
description: One or more model targets to process
minItems: 1
maxItems: 20
uniqueItems: true
type: array
items:
description: >-
A target specifying a model and desired output
formats.
additionalProperties: false
type: object
properties:
model:
description: >-
Model to run. See the Models page for available
options.
minLength: 2
maxLength: 255
type: string
formats:
description: >-
Output file formats: "wav", "mp3" for audio
models, "json" for transcription and detection
models.
uniqueItems: true
type: array
items:
type: string
residual:
description: >-
Optional. Return the residual (everything not in
the target stem).
type: boolean
language:
description: >-
Optional. ISO 639-1 language code (e.g. "en").
Only applies to transcription and alignment
models. Auto-detected if omitted.
minLength: 2
maxLength: 2
type: string
transcriptAssetId:
description: >-
Optional. Asset ID of an existing transcript to
align against. Only used with the alignment model.
Mutually exclusive with transcriptUrl.
minLength: 2
type: string
transcriptUrl:
description: >-
Optional. HTTPS URL of an existing transcript to
align against. Only used with the alignment model.
Mutually exclusive with transcriptAssetId.
format: uri
minLength: 2
type: string
required:
- model
- formats
required:
- assetId
- targets
example:
assetId: your_asset_id
targets:
- model: vocals
formats:
- wav
- model: instrumental
formats:
- wav
- additionalProperties: false
type: object
properties:
url:
description: Public HTTPS URL of an input media file
format: uri
type: string
writeDestination:
description: >-
Optional. S3 URI prefix to write outputs under (e.g.
"s3://my-bucket/outputs"). The bucket must be covered by
a configured storage integration. Outputs are organized
as
//targets//output/.
See Custom S3 Write Destination.
format: uri
type: string
metadata:
description: >-
Client-provided metadata. Stored and returned as-is in
responses and webhooks.
maxLength: 4096
type: string
targets:
description: One or more model targets to process
minItems: 1
maxItems: 20
uniqueItems: true
type: array
items:
description: >-
A target specifying a model and desired output
formats.
additionalProperties: false
type: object
properties:
model:
description: >-
Model to run. See the Models page for available
options.
minLength: 2
maxLength: 255
type: string
formats:
description: >-
Output file formats: "wav", "mp3" for audio
models, "json" for transcription and detection
models.
uniqueItems: true
type: array
items:
type: string
residual:
description: >-
Optional. Return the residual (everything not in
the target stem).
type: boolean
language:
description: >-
Optional. ISO 639-1 language code (e.g. "en").
Only applies to transcription and alignment
models. Auto-detected if omitted.
minLength: 2
maxLength: 2
type: string
transcriptAssetId:
description: >-
Optional. Asset ID of an existing transcript to
align against. Only used with the alignment model.
Mutually exclusive with transcriptUrl.
minLength: 2
type: string
transcriptUrl:
description: >-
Optional. HTTPS URL of an existing transcript to
align against. Only used with the alignment model.
Mutually exclusive with transcriptAssetId.
format: uri
minLength: 2
type: string
required:
- model
- formats
required:
- url
- targets
example:
url: https://example.com/song.wav
targets:
- model: vocals
formats:
- wav
- model: instrumental
formats:
- wav
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
description: Unique identifier of the Task
type: string
createdAt:
format: date-time
description: Timestamp of when the Task was created
type: string
completedAt:
anyOf:
- format: date-time
description: Timestamp of when the Task was completed
type: string
- type: 'null'
clientId:
description: Unique identifier of the client
type: string
cost:
description: Processing cost in credits
type: number
assetId:
description: >-
Asset ID of an input media file. Mutually exclusive with
url
type: string
url:
anyOf:
- description: >-
URL of an input media file. Mutually exclusive with
assetId
type: string
- type: 'null'
writeDestination:
anyOf:
- description: >-
S3 URI prefix outputs were written under. Outputs are
organized as
//targets//output/.
Only present when a custom write destination was
provided.
type: string
- type: 'null'
metadata:
description: >-
Client-provided metadata. Stored and returned as-is in
responses and webhooks.
type: string
targets:
description: Processing targets and their current status
type: array
items:
type: object
properties:
id:
description: Unique identifier of the target
type: string
model:
description: >-
Model to run. See the Models page for available
options.
type: string
status:
description: >-
Status of the target: 'processing' – actively
running; 'completed' – results ready in output;
'error' – see error field for details
enum:
- processing
- completed
- error
type: string
formats:
type: array
items:
description: Output file formats (e.g. "wav", "mp3", "json")
type: string
output:
description: >-
Downloadable output files for this target. Populated
when status is "completed".
type: array
items:
type: object
properties:
name:
description: Filename of the output asset
type: string
format:
description: Format of the output file
type: string
link:
description: >-
Presigned download URL. Expires after one hour
— re-fetch the Task for a fresh link.
type: string
required:
- name
- format
- link
cost:
description: Processing cost in credits
type: number
error:
anyOf:
- type: object
properties:
code:
description: Error code
type: number
message:
description: Error message
type: string
required:
- code
- message
- type: 'null'
duration:
description: Processed audio duration in seconds
type: number
residual:
description: Include residual with results
type: boolean
language:
description: >-
ISO 639-1 two-letter language code. Improves model
accuracy and timing alignment for transcription and
alignment models. If omitted, the model will attempt
to auto-detect.
type: string
transcriptUrl:
description: URL to transcript file for alignment
type: string
transcriptAssetId:
description: Asset ID of a transcript for alignment
type: string
required:
- id
- model
- status
- formats
- output
components:
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header
````