Skip to main content

Create API

Use the Create API to programmatically generate assets using Generative AI. Use one or more built in services or third party providers to create assets using text to speech, text generation, text to image and avatar generation.

Generate an asset using a provider​

Assets are generated by POSTing a JSON payload to the Create API's asset endpoint:

POST https://api.shotstack.io/create/{{ENV}}/assets/

Where {{ENV}} is the environment you are working in, for example stage or v1.

A typical request, using cURL looks like this:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     https://api.shotstack.io/create/stage/assets/
     -d '
{
    "provider": "shotstack",
    "options": {
        "type": "text-to-speech",
        "text": "The future of media production is here with the help of the Shotstack Create API",
        "voice": "Matthew"
    }
}'

In this example the Shotstack built in text-to-speech service is used to generate an audio file from the text string provided using the voice Matthew.

The JSON payload always includes the following properties:

{
    "provider": "shotstack",
    "options": {
        "type": "text-to-speech",
        // other options...
    }
}

The provider property specifies the provider to use to generate the asset. In the example above it is set to shotstack but to call a third party provider you would use the provider's name, for example elevenlabs.

The options property is an object containing the type and additional options for the provider. The options vary depending on the provider but the type property is always required. In the example above the type is set to text-to-speech to use the Shotstack built in text-to-speech service. There are other types available depending on the provider, for example text-to-image or text-to-avatar.

The options for each provider are documented in the providers section.

The request above returns a response similar to below which includes the id of the asset and the initial status of the request:

{
    "data": {
        "type": "asset",
        "id": "01duc-fa2a6-t5f7e-2foa3-y88ef",
        "attributes": {
            "owner": "5ca6hu7s9k",
            "provider": "shotstack",
            "type": "text-to-speech",
            "status": "queued",
            "created": "2023-11-04T06:11:19.008Z",
            "updated": "2023-11-04T06:11:19.008Z"
        }
    }
}

Check the generation status of an asset​

When an asset is created it is added to a queue and processed asynchronously. The status of an asset can be checked by making a GET request to the asset endpoint with the asset ID appended to the URL.

GET https://api.shotstack.io/create/{{ENV}}/assets/{{ID}}

The following cURL requests retrieves the asset we just created using the id returned in the response above:

curl -X GET \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     https://api.shotstack.io/create/stage/assets/01duc-fa2a6-t5f7e-2foa3-y88ef

The response will look similar to below:

{
    "data": {
        "type": "asset",
        "id": "01duc-fa2a6-t5f7e-2foa3-y88ef",
        "attributes": {
            "owner": "5ca6hu7s9k",
            "provider": "shotstack",
            "type": "text-to-speech",
            "url": "https://shotstack-create-api-stage-assets.s3.amazonaws.com/5ca6hu7s9k/01duc-fa2a6-t5f7e-2foa3-y88ef.mp3",
            "status": "done",
            "created": "2023-11-04T06:11:19.008Z",
            "updated": "2023-11-04T06:11:24.323Z"
        }
    }
}

The response includes the url property which is the location of the generated asset, in this case an mp3 file. The status property will be done when the asset is ready to use. If the request is made before the asset is ready the status will be queued or processing. If it fails for any reason the status will be failed and an error message will be included in the response.