# 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 [audio](../ai-speech-generation), [image](../ai-image-generation) and [video](../ai-video-generation) assets.

### Generate an asset using a provider

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

```bash
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:

```bash
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:

```json
{
    "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.

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

```json
{
    "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.

```bash
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:

```bash
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:

```json
{
    "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.