Retrieve Task

Retrieve an async generation task. The video-to-sfx, text-to-sfx, and audio-ducking endpoints return a task_id; the video-to-music and text-to-music endpoints do too when called with mode=async. Poll this endpoint every 2 to 5 sec until the status is succeeded or failed. Only these async tasks are available here — any other task id returns 404.

GET/v1/tasks/{task_id}

curl "https://api.sonilo.com/v1/tasks/9f5f2f7e-..." \
  -H "Authorization: Bearer sk_your_api_key"

import requests

resp = requests.get(
    "https://api.sonilo.com/v1/tasks/9f5f2f7e-...",
    headers={"Authorization": "Bearer sk_your_api_key"},
)
resp.raise_for_status()
task = resp.json()
print(task["status"])

const resp = await fetch(
  "https://api.sonilo.com/v1/tasks/9f5f2f7e-...",
  { headers: { Authorization: "Bearer sk_your_api_key" } },
);
const task = await resp.json();
console.log(task.status);

{
  "task_id": "9f5f2f7e-...",
  "type": "text_to_sfx",
  "status": "processing"
}

Authorization

Authenticate via Bearer token. Generate keys at the API Keys page and pass them in the Authorization header on every request.

Authorization: Bearer sk_your_api_key

Query Parameters

task_idstring (path)required

The task_id returned by POST /v1/video-to-sfx, POST /v1/text-to-sfx, POST /v1/audio-ducking, or POST /v1/video-to-music or POST /v1/text-to-music with mode=async.

Response

task_idstring

The task identifier.

typestring

The task type: video_to_sfx, text_to_sfx, audio_ducking, video_to_music, or text_to_music.

statusstring

One of processing, succeeded, or failed.

duration_secondsnumber

The duration of the generated audio or video, in seconds. Present when the task succeeded.

audioobject

Present when an SFX task succeeded — the generated audio, hosted on Sonilo storage.

audio.urlstring

A temporary download URL for the audio file, valid for 7 days.

audio.content_typestring

The audio MIME type — audio/mp4 (m4a, the default) or audio/wav when the request set output_format=wav (video-to-music and text-to-music only).

audio.file_sizeinteger

The audio file size in bytes.

audio[]array

For video-to-music and text-to-music tasks, audio is an array of generated audio streams (one entry per parallel output) instead of the single object SFX returns.

audio[].stream_indexinteger

0-based index identifying which parallel output stream this entry is.

audio[].sample_rateinteger

Audio sample rate in Hz.

audio[].channelsinteger

Number of audio channels.

titleobject

Generated track title (video-to-music only). Only present when the account's stream event whitelist includes title.

output_urlstring

Present when an audio-ducking task succeeded — a presigned, time-limited download URL for the mixed result.

output_typestring

Present when an audio-ducking task succeeded — audio, or video when the voice input was a video (output_url then points to a new video with the original picture and the ducked audio track).

vocalsobject

Present when a video-to-music task succeeded with isolate_vocals — the isolated vocals stem.

vocals.urlstring

A temporary download URL for the vocals stem, valid for 7 days.

vocals.content_typestring

The vocals file's MIME type, e.g. audio/wav. video-to-music (isolate_vocals) only.

vocals.file_sizeinteger

The vocals file size in bytes. video-to-music (isolate_vocals) only.

mux[]array

Present when a video-to-music task succeeded with isolate_vocals — the isolated vocals mixed with the generated music, automatically leveled so the music doesn't bury the vocals, one entry per parallel output stream (same alignment as audio).

mux[].stream_indexinteger

0-based index identifying which parallel output stream this mux entry corresponds to.

mux[].urlstring

A temporary download URL for the mixed vocals+music file, valid for 7 days.

mux[].content_typestring

The mux file's MIME type — audio/mp4 (m4a, the default) or audio/wav when the request set output_format=wav.

mux[].file_sizeinteger

The mux file size in bytes.

errorobject

Present when failed — an object with a code and a human-readable message.

refundedboolean

Present when failed — whether the charge was reversed. Refunds are issued automatically on failure but may take a few sec to be reflected; if false right after a failure, poll once more.

curl "https://api.sonilo.com/v1/tasks/9f5f2f7e-..." \
  -H "Authorization: Bearer sk_your_api_key"

import requests

resp = requests.get(
    "https://api.sonilo.com/v1/tasks/9f5f2f7e-...",
    headers={"Authorization": "Bearer sk_your_api_key"},
)
resp.raise_for_status()
task = resp.json()
print(task["status"])

const resp = await fetch(
  "https://api.sonilo.com/v1/tasks/9f5f2f7e-...",
  { headers: { Authorization: "Bearer sk_your_api_key" } },
);
const task = await resp.json();
console.log(task.status);

{
  "task_id": "9f5f2f7e-...",
  "type": "text_to_sfx",
  "status": "processing"
}