SDK Migration guide
Upgrade from legacy API.audio SDK to AudioStack
apiaudio -> audiostack sdk migration guide
In general the audiostack SDK has a large number of improvements over its predecessor. It operates in a broadly similar way.
Objects
All objects are now split into one of four families, these are Content, Speech, Production and Delivery.
The following objects have been migrated as follows:
Script.<function>() -> Content.Script.<function>()
Media.<function>() -> Content.Media.<function>()
Speech.<function>() -> Speech.TTS.<function>()
Voice.<function>() -> Speech.Voice.<function>()
Lexi.<function>() -> Speech.Diction.<function>()
Mastering.<function>() -> Production.Mix.<function>()
Sound.<function>() -> Production.Sound.<function>()
The following objects are deprecated
- Birdcache
The following objects are in development
- Connector
- Orchestrator
- Webhooks
The following objects are new.
Delivery.Encoder
Response types
Our API supports the following HTTP protocools, and the SDK represents these though methods on each object. I.e. Script.create() represents making a POST request.
POST: .create()
- creates a new resource, in the SDK this returns an
item
of type resource (i.e.script
)
PUT .update()
- updates a new resource, in the SDK this returns an updated
item
of type resource (i.e.script
)
GET: .get()
or .list()
- Gets an existing resource, in the SDK this returns an
item
of type resource (i.e.script
), or alist
ofitems
DELETE .delete()
- Deletes a resource, in the SDK this does not return any object
Object types
Calls to most object functions, will create an instance of an item object. For example, calling Script.create()
returns a Script.Item
object. These objects can have operations such as update
, delete
and download
applied directly to them. For example, a script can be deleted either through the static Script.delete()
method or by calling .delete()
on a Script.Item
object.
Per service changes
The following section outlines changes for each service.
Script
Breaking changes
- Script create always creates a new resource, it never updates an existing one.
scriptId
can no longer be defined by the end-user. In addition the script syntax has changed.
New features
- Scripts can be updated with the
.update
method.
TTS (formally just Speech)
Breaking changes
- Speech files can no longer be retrieved by
scriptId
, instead every call toTTS.create()
will create a new resource, and return a uniquespeechId
. Likewise the URL returned for each TTS asset is now a unique link and will never expire.
New features
- TTS assets can be listed and deleted by
scriptId
,scriptName
,projectName
andmoduleName
. - TTS resources can be made public with the
public
value inTTS.create()
- A
TTS.create()
request can take either ascriptId
str value, or ascriptItem
object (the client side python object return from aScript.create()
call).
Mix (formally Mastering)
Breaking changes
- Mastered files can no longer be retrieved by scriptId, instead every call to
Mix.create()
will create a new resource, and return a uniqueproductionId
. Likewise the URL returned for each TTS asset is now a unique link and will never expire. - To produce a mixed file (formally mastering) requires a
speechId
instead of ascriptId
endFormat
can no longer be specified in theMix.create()
call, instead see theDelivery
endpoints.
New features
- Mixed assets can be listed and deleted by
scriptId
,scriptName
,projectName
andmoduleName
. - Mixed resources can be made public with the
public
value inMix.create()
- A
Mix.create()
request can take either aspeechId
str value, or aspeechItem
object (the client side python object return from aSpeech.create()
call).
v1 vs v2
The following apiaudio code:
import apiaudio
apiaudio.api_key = "your-key"
# script creation
script = apiaudio.Script.create(scriptText="Hello world")
# speech creation
response = apiaudio.Speech.create(scriptId=script["scriptId"], voice="Aria")
print(response)
# mastering process
response = apiaudio.Mastering.create(
scriptId=script.get("scriptId"),
soundTemplate="jakarta"
)
print(response)
# download
filepath = apiaudio.Mastering.download(scriptId=script["scriptId"], destination=".")
print(filepath)
Can be reproduced in v2 as follows:
import audiostack
audiostack.api_key = "your-key"
script = audiostack.Content.Script.create(scriptText="hello world")
print(script.message, script.scriptId)
tts = audiostack.Speech.TTS.create(scriptItem=script, voice="Aria")
print(tts)
tts.download(autoName=True)
mix = audiostack.Production.Mix.create(speechItem=tts, soundTemplate="jakarta")
print(mix)
enc = audiostack.Delivery.Encoder.encode_mix(productionItem=mix, preset="mp3_low")
enc.download()
Updated about 1 year ago