file/status
Check if a result file is ready to download (applies to non-blocking requests only).
Requesting the status of the file before download allows you to check the existence of the file beforehand. Furthermore, the response will indicate the percentage of the file that has already been processed.
This feature is only relevant if you have started a processing or analysis task asynchronously (by appending "&blocking=false" to the URL). The result file for that task can not be downloaded before processing is complete - if you try, you will get an error "409 - File operation is still in progress".
Parameters
| Parameter | Type | Description |
|---|---|---|
| access_id required | uuid | One of your personal access_ids |
| file_id required | file | The file_id of a file that is being written by a non-blocking task |
| format optional |
string [wav, aif, au, flax, mp3-cbr, mp3-vbr, ogg, xml, json, jsonp, xmlp] default: mp3-vbr |
The format to use in the response. If you select an audio format, see the table below that lists which parameters are available to control the quality for each format.
Note that for the formats "jsonp" or "xmlp", the HTTP status code will always be 200. |
| callback optional | string |
Callback function name required when using the format "jsonp" or "xmlp." |
| foo_string optional | string |
Arbitrary string to add to the logs.
Allows you to add any strings you might find helpful for later analysis of the request logs. |
Usage example
These examples use the cURL command line tool to execute a series of http requests that show you how to query the progress of a non-blocking task. Please note that you need to replace the access_id in the examples with one of yours or you will receive an error ("403 - File upload not allowed").
First, a processing task (the reverb effect) is started with a local file "track.mp3" that contains several minutes of audio:
$ ACCESS_ID=deb464f7-f374-4ae8-a0b4-6c45cab86705
$ curl https://api.sonicapi.com/process/reverb?access_id=$ACCESS_ID\&blocking=false -Finput_file=@track.mp3
<?xml version="1.0" encoding="utf-8"?>
<response>
<status code="201"/>
<file file_id="b3fc0fd5-ec2c-489f-b1c3-867627092739" status="working"
remaining_lifetime_seconds="568"
href="/file/download?file_id=b3fc0fd5-ec2c-489f-b1c3-867627092739"/>
</response>
Because blocking=false was specified, the server responded immediately with the file_id of the result file. status="working" indicates that the result can not be downloaded yet. You can now request file/status with that file_id to query the progress of the task:
$ FILE_ID=b3fc0fd5-ec2c-489f-b1c3-867627092739
$ curl https:/api.sonicapi.com/file/status?access_id=$ACCESS_ID\&file_id=$FILE_ID
<?xml version="1.0" encoding="utf-8"?>
<response>
<status code="200"/>
<file file_id="b3fc0fd5-ec2c-489f-b1c3-867627092739" status="working"
remaining_lifetime_seconds="567"
href="/file/download?file_id=b3fc0fd5-ec2c-489f-b1c3-867627092739"
progress="40"/>
</response>
The response shows that the task is 40% complete (as indicated by progress="40")
$ curl https:/api.sonicapi.com/file/status?access_id=$ACCESS_ID\&file_id=$FILE_ID
<?xml version="1.0" encoding="utf-8"?>
<response>
<status code="200"/>
<file file_id="b3fc0fd5-ec2c-489f-b1c3-867627092739" status="ready"
remaining_lifetime_seconds="564"
href="/file/download?file_id=b3fc0fd5-ec2c-489f-b1c3-867627092739"
progress="100"/>
</response>
As soon as progress reaches 100% (and status switches to "ready") you can download the result file:
$ curl https://api.sonicapi.com/file/download?access_id=$ACCESS_ID\&file_id=$FILE_ID > reverb.mp3
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 20.4M 0 20.4M 0 0 473k 0 --:--:-- 0:00:44 --:--:-- 476k