Skip to main content

Ingesting and Uploading Source Files

The Ingest API allows you to fetch and upload source files (videos, images, audio and fonts) to use in your edits. The examples below show you how to fetch files from URLs and upload files directly. You can also apply transformations to source files once ingested to create renditions.

Fetch a file from a URL​

If you have your own storage or hosting solution and want to transfer assets to Shotstack before editing, use the sources endpoint and include the file URL in the payload body:

curl -X POST https://api.shotstack.io/ingest/stage/sources \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf' \
     -d '
{
    "url": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4"
}'

The example above requests the url https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4 be ingested to the stage environment.

You should receive a response similar to below:

{
    "data": {
        "type": "source",
        "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2"
    }
}

The file will be fetched asynchronously from the URL which may take a some time depending on the file size, bandwidth and geographic location. You can check the status of the transfer by polling the individual sources resource.

Upload files directly​

If the file you want to ingest is not already stored online you can upload it directly from your application using a signed URL. By using direct uploads you do not need to worry about setting up or managing your own storage and can use Shotstacks infrastructure instead.

To upload a file you first need to request a signed URL:

curl -X POST https://api.shotstack.io/ingest/stage/upload \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'

The request above calls the stage environment and returns a signed URL in the response like below:

{
    "data": {
        "type": "upload",
        "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
        "attributes": {
            "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
            "url": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D",
            "expires": "2023-01-02T02:47:37.260Z"
        }
    }
}

The url at data.attributes.url is the signed URL that you use in the next step to upload the file.

Uploading the file​

To upload a file from your desktop or server you can use the following cURL command:

curl -X PUT -T video.mp4 https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/source?AWSAccessKeyId=ASIAWJV3NVDML6LI2ZVG&Expires=1672819007&Signature=9M76gBA%2FghV8ZYvGTp3alo5Ya%2Fk%3D&x-amz-acl=public-read&x-amz-security-token=IQoJb3JpZ2luX2VjEJ%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDmFwLXNvdXRoZWFzdC0yIkcwRQIhAJHrqMCRk7ACXuXmJICTkADbx11e2wUP0RZ3KRdN3%2BGwAiAYt%2FIHlM8rcplCgvsvqH%2BBtSrlCW%2BUeZstwuwgq45Y3iqbAwjo%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAMaDDQzMzExNTIxMTk5MiIMtFX%2Bb1klptd8HXQvKu8Cd0xpHti7cRWkPxQz3foEWSYu1U8In64Qsi6TFK%2BmiOhVnUkHK%2BLSIwF1yQFMK2oTzVXwrEFEsyqlf%2FPZ9j3OL9eLlB7G5AqbC16hjXXR3psipp0dE2uvCV2d%2BIDYgcf1MKmzE0FDfN4wyTez%2Bd%2F3y8nfAtWB%2FCB0wU8AtKNUI7hwNbCYMgCa8QUeAH2UOrriDaN379vKXK%2B1XVplhhuvLX3aC1D0St2U6lC5yaDtZbLGEyymQPhgpp5Mam6jVzHVXXX4%2FvkQSNWbDMuMFd13fqdut9uMPkq4vhZgCmyQsibC7AnrK21QopLY%2F0vhHvPUhSkzRDKjiQou0vDrbTnT4yJLY5RCs9G65yisi6jbyUUbJTUgrME7PPPihs7kM5L%2FGjhmKqe9rNPuzKC%2FISRcmVtAPleX7tqPI7H%2BuEIobS%2FE%2B1jV4oNUFQA549prw3546FXds%2FgCLKRU%2BvxUyi2yKS8U0QC%2FNLMg2p9c81%2BaDCCqxtSdBjqdAcxGASzQwP6hHbfzC2hlnxn%2Bnf4MddgpIPFxvpV18Sy9vUYSU52mrsZK%2FxPcxrg1AM94v0aaW%2FaRE1ESTF2hXJrAJZkDNDPEBQBmcP3ylj4Bf5MsP%2FCspFoF6TvXZPYkH1lSlWHT8OTOugLji7%2F9qb9a6bKzFJqvcS0EiT7v5LCOMOpVA%2FAg9RM0yerN4Zot%2FREHgCSzajNII9Xio%2F0%3D

In this example a file called video.mp4 is uploaded to Shotstack. The signed URL is appended to the end of the command.

The upload process will be performed in the forground and should not be interupted until it completes. If the file upload is interupted the command will need to be ran again.

Once complete you can poll the sources resource to get the file details.

Note

Do not include the Content-Type header with the upload request. Including this header will give you an authentication error as it modifies the URL signature. Omit the header and we will work out the content type after the file is uploaded.

Get an individual source files details​

Look up the details and ingestion status of a file by its id. Use the id returned when you fetch a URL or perform a direct upload:

curl -X GET https://api.shotstack.io/ingest/stage/sources/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2 \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'

The example above calls the sources endpoint in the stage (sandbox) environment with the id zzytey4v-32km-kq1z-aftr-3kcuqi0brad2 which was returned by the fetch URL request.

The response will look similar to:

{
    "data": {
        "type": "source",
        "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
        "attributes": {
            "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
            "owner": "5ca6hu7s9k",
            "input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
            "source": "https://shotstack-ingest-api-stage-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
            "status": "ready",
            "width": 1920,
            "height": 1080,
            "duration": 25.86,
            "fps": 23.967,
            "created": "2023-01-02T01:47:18.973Z",
            "updated": "2023-01-02T01:47:37.260Z"
        }
    }
}

The URL at data.attributes.source is the file saved with Shotstack that you can use when editing videos. If the file is still being transferred or uploaded the status will show as queued or importing. If there is an error the status will be failed.

List all ingested files​

You can retrieve a list of all your ingested source files. Files are returned in date order with the most recent first.

curl -X GET https://api.shotstack.io/ingest/stage/sources \
     -H 'Accept: application/json' \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'

The response returns an array of source files like below:

{
    "data": [
        {
            "type": "source",
            "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
            "attributes": {
                "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
                "owner": "5ca6hu7s9k",
                "input": "https://github.com/shotstack/test-media/raw/main/captioning/scott-ko.mp4",
                "source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzytey4v-32km-kq1z-aftr-3kcuqi0brad2/source.mp4",
                "status": "ready",
                "width": 1920,
                "height": 1080,
                "duration": 25.86,
                "fps": 23.967,
                "created": "2023-01-02T01:47:18.973Z",
                "updated": "2023-01-02T01:47:37.260Z"
            }
        },
        {
            "type": "source",
            "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
            "attributes": {
                "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
                "owner": "5ca6hu7s9k",
                "source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/video.mp4",
                "status": "ready",
                "width": 1920,
                "height": 1080,
                "duration": 18.24,
                "fps": 30,
                "created": "2023-01-02T01:53:28.973Z",
                "updated": "2023-01-02T01:53:57.460Z"
            }
        }
    ]  
}
Note

In the example above the second file does not have an input file. The second file was uploaded using a direct upload so there is no input URL.

Delete a file from storage​

To delete a file by id send a DELETE request to the sources resource with the id of the file to delete:

curl -X DELETE https://api.shotstack.io/ingest/stage/sources/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl \
     -H 'x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf'

A 204 response code is returned, the file will be deleted from storage and the status updated to deleted, like this:

{
    "data": {
        "type": "source",
        "id": "zzytey4v-32km-kq1z-aftr-3kcuqi0brad2",
        "attributes": {
            "id": "zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl",
            "owner": "5ca6hu7s9k",
            "source": "https://shotstack-ingest-api-v1-sources.s3.ap-southeast-2.amazonaws.com/5ca6hu7s9k/zzyafe82-4tvb-ku1r-87ty-0io5sv0mtrdl/video.mp4",
            "status": "deleted",
            "width": 1920,
            "height": 1080,
            "duration": 18.24,
            "fps": 30,
            "created": "2023-01-02T01:53:28.973Z",
            "updated": "2023-01-02T01:53:57.460Z"
        }
    }
}
Note

All Ingest API responses follow the JSON:API specification making it easy to consume using an existing library.