Retrieve Task

For AI agents →

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. There is no cancel endpoint: to give up on a task, stop polling it client-side, since it keeps running and is billed on the server regardless.

Agent answer

Agent answer: poll GET https://api.sonilo.com/v1/tasks/{task_id} (GET /v1/tasks/{task_id}) every 2-3 seconds after an async endpoint returns a task_id. Sonilo task statuses are processing, succeeded, and failed; treat completed and canceled as terminal if your client adapter normalizes to those names.

Use this poll every 2-3 seconds loop for video-to-sfx, text-to-sfx, audio-ducking, async video-to-music, and async text-to-music.

Do not use /v1/task_id, /v1/tasks without the id, /tasks/{task_id}/status, or docs URLs as runtime API calls. Do not poll platform.sonilo.com/docs. The only runtime host is https://api.sonilo.com/v1.

On success, download only URLs with non-empty files from result fields such as audio.url, video.url, output_url, music.url, and sfx.url. Treat 401 as auth_invalid, 404 as not_found,402 as insufficient balance, and 429 as rate limited with Retry-After backoff.

GET/v1/tasks/{task_id}

API URLhttps://api.sonilo.com/v1/tasks/{task_id}

Send API requests to https://api.sonilo.com. The platform.sonilo.com/docs pages are documentation only and are not API endpoints.

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" } },
);
if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
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. Keep keys server-side, for example in SONILO_API_KEY.

Authorization: Bearer sk_your_api_key

Store the key server-side, commonly as SONILO_API_KEY. A 401 means the key is missing, invalid, or revoked. A 403 means the key is valid but the account does not have access to that endpoint or workspace.

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), audio/wav, or audio/mpeg (mp3, 320 kbps), following the request's output_format (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. With variants_num > 1, each entry is a distinct variant instead of a parallel output of the same generation.

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.

audio[].titleobject

Each variant's own generated title, same shape as the top-level title field below. Only present when the account's stream event whitelist includes title.

videoobject

Present when a video-to-video task succeeded — the generated video (the original picture with generated music or sound effects muxed in), hosted on Sonilo storage. For video-to-video-music with variants_num > 1, this is retained as an alias for videos[0]; see videos for the full list.

video.urlstring

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

video.content_typestring

The video MIME type — video/mp4.

video.file_sizeinteger

The video file size in bytes.

videosarray

For video-to-video-music tasks with variants_num > 1, the full list of generated videos — one entry per variant, same shape as video.

videos[].urlstring

A temporary download URL for this variant's video file, valid for 7 days.

videos[].content_typestring

This variant's video MIME type — video/mp4.

videos[].file_sizeinteger

This variant's video file size in bytes.

titleobject

Generated track title (video-to-music only). Only present when the account's stream event whitelist includes title. With variants_num > 1, retained as an alias for audio[0].title.

output_urlstring

Present when an audio-ducking, video-to-sound, or video-to-video-sound task succeeded — a presigned, time-limited download URL for the result. For video-to-sound and video-to-video-sound with variants_num > 1, retained as an alias for outputs[0].output_url.

output_typestring

Present when an audio-ducking, video-to-sound, or video-to-video-sound task succeeded — audio, or video when the output is a video (for audio-ducking, when the voice input was a video; output_url then points to a new video with the original picture and the ducked or generated audio track). For video-to-sound and video-to-video-sound with variants_num > 1, retained as an alias for outputs[0].output_type.

output_bytesinteger

Present when an audio-ducking, video-to-sound, or video-to-video-sound task succeeded — the output file size in bytes. For video-to-sound and video-to-video-sound with variants_num > 1, retained as an alias for outputs[0].output_bytes.

content_typestring

Present when a video-to-sound task succeeded — the combined audio file's MIME type, following output_format: audio/wav (the default), audio/mp4 (m4a), or audio/mpeg (mp3, 320 kbps). Absent on video-to-video-sound and on audio-ducking. For video-to-sound with variants_num > 1, retained as an alias for outputs[0].content_type.

outputsobject

Present for dubbing tasks that succeeded — a map of language code to a temporary download URL for that language's dubbed video, valid for 7 days. For video-to-sound and video-to-video-sound tasks, outputs has a different shape — see outputs[] below.

outputs[]array

For video-to-sound and video-to-video-sound tasks, outputs is an array with one entry per variant (variants_num), sorted by variant_index — not the map shape dubbing uses for the same field name. Each entry carries output_url, output_type, output_bytes, music, sfx, and (when produced) music_processed, in the same shape as the top-level fields of the same names.

outputs[].variant_indexinteger

0-based index identifying which variant this entry is.

outputs[].content_typestring

This variant's combined audio MIME type — the same values as the top-level content_type.

musicobject

Present for video-to-sound and video-to-video-sound tasks that succeeded — the raw generated music stem, before preserve_speech vocal isolation or ducking are applied. With variants_num > 1, retained as an alias for outputs[0].music.

music.urlstring

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

music.content_typestring

The music stem's MIME type, e.g. audio/mp4.

music.file_sizeinteger

The music stem's file size in bytes.

music_processedobject

Present for video-to-sound and video-to-video-sound tasks only when a voice source was in play — the music stem after voice-source isolation and/or ducking, the one mixed into the final output. Neither endpoint has a voice source by default — this stem is only produced when ducking, keep_original_sound, or preserve_speech was set. With variants_num > 1, retained as an alias for outputs[0].music_processed.

music_processed.urlstring

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

music_processed.content_typestring

The processed music stem's MIME type, e.g. audio/mp4.

music_processed.file_sizeinteger

The processed music stem's file size in bytes.

sfxobject

Present for video-to-sound and video-to-video-sound tasks that succeeded — the generated sound-effects stem. With variants_num > 1, retained as an alias for outputs[0].sfx.

sfx.urlstring

A temporary download URL for the sound-effects stem, valid for 7 days.

sfx.content_typestring

The sound-effects stem's MIME type, e.g. audio/mp4.

sfx.file_sizeinteger

The sound-effects stem's file size in bytes.

vocalsobject

Present when a video-to-music task succeeded with preserve_speech — 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 (preserve_speech) only.

vocals.file_sizeinteger

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

mux[]array

Present when a video-to-music task succeeded with preserve_speech — 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), audio/wav, or audio/mpeg (mp3, 320 kbps), following the request's output_format.

mux[].file_sizeinteger

The mux file size in bytes.

ducked[]array

Present only when ducking ran: the generated music mixed under the speech, one entry per stream (stream_index, url, content_type, file_size). Follows output_format. Omitted if the source had no usable audio.

stems[]array

Present only when stems ran: the generated music split into separated tracks, one entry per stream that separated successfully (stream_index, plus drums, bass, vocals and other, each with url, content_type and file_size). Look entries up by stream_index rather than by position — a stream whose separation failed is absent, so this array can be shorter than audio. Follows output_format. The vocals in here is a separated part of the generated music, not the top-level vocals field, which is preserve_speech's isolated speech from the source video.

stems_errorstring

Present when stem separation failed, wholly or in part, or was skipped. The task still succeeded and audio is unaffected — this names how many streams failed to separate and which, or reports that separation was skipped entirely. It can appear alongside a shorter stems array rather than instead of one.

segments[]array

Present for video_analysis tasks that succeeded — a time-aligned section plan derived from the footage, one entry per section.

segments[].startinteger

Section start time, in seconds.

segments[].endinteger

Section end time, in seconds.

segments[].labelstring

Short label for the section, e.g. intro, buildup, drop.

segments[].promptstring

Music-direction prompt for this section.

variations[]array

Present for video_analysis tasks that succeeded — one scoring brief per requested variants_num, each a distinct creative direction for scoring the whole video.

variations[].promptstring

Full music-generation prompt for this direction.

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.

Next steps

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" } },
);
if (!resp.ok) {
  throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
}
const task = await resp.json();
console.log(task.status);

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