Ingesting Container Images
Objective
This tutorial will guide you through the process of ingesting images into the SyncTV service and linking them with their respective container objects.
Requirements
  • An admin account with your SyncTV service.
  • An understanding of the signature generation process.
  • An existing Container object.
    • Container 3531 for this tutorial.
  • An existing image within reach of our servers.
  • A familiarity with RESTful APIs.
APIs Covered
Step 1
Determining File Path
All ingests require that the item being ingested by located on our servers. There are several ways to place content on our servers, they are fairly straight forward and outlined in our Content Transferring guide.

This tutorial assumes the file being ingested is within the root folder itself. As in the content was uploaded directly to your company's directory on our server via SFTP, Aspera or hard drive delivery.

It is also possible to have our ingest service retrieve content from publicly accessible web resources by using a full URL as the file path. This is not encouraged for any files larger then 10MB.


Example URL
cdn01.mywebsite.com/wp-content/uploads/1993/03/prettypicture.jpg
Step 2
Create the Ingest
Creating an ingest is the first step to ingesting images into the SyncTV service. When creating an image ingest, you must already have the container object created within the system. This is required because all ingests are tied to a specific object. In this case container 3531.

In order to ingest video you must POST the file path to the ingest image API, as demonstrated below.
    [POST]https://service_name.synctv.com/api/v2/containers/3531/ingest_images.json?access_id=3888&ingest_image[file_path]=The_score_500_375.png&signature=3483dff9e1062226027dac725fa21a83
Example Response
{
	"response": {
		"ingest_image": {
			"id": 8,
			"ingestable_type": "Container",
			"ingestable_id": 3531,
			"file_path": "The_score_500_375.png",
			"file_size": null,
			"state": "reset",
			"status": "ok",
			"stage": "none",
			"message": null,
			"iteration": 0,
			"removable_assets": false
		},
		-
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}
							
This reseponse contains the ID of the ingest which will be used in the next steps. For a full description of all attributes in this response, please visit the Ingest Images API documentation.
Step 3
Starting the Ingest
With the ingest configured it is now possible to start the processing. The ingest process breaks the image down and re-encodes it in multiple resolutions and file formats for viewing on all supported devices.

Starting the ingest requires that you send a PUT request to the ingest images start API with the ID of the container the ingest is attached to as well as the ID of the image ingest itself. This is demonstrated below.
    [PUT]https://service_name.synctv.com/api/v2/containers/3531/ingest_images/7/start.json?access_id=3888&signature=3872d86278c88acf23edc080d957fe3c
Example Response
All PUT requests made to the SyncTV service return only HTTP success or failure codes, no content.
Step 4
Checking the Ingest Status
While most ingests are successful, it is possible for something to go wrong. For this reason you may want to check the ingest status.

To check the status of a specific ingest you must know the ID of the ingest and the container it is associated with. You must then GET from the ingest images API with the ID of the container the ingest is attached to as well as the ID of the image ingest itself. This is demonstrated below.
    [GET]https://service_name.synctv.com/api/v2/containers/3431/ingest_images/7.json?access_id=3888&signature=3872d86278c88acf23edc080d957fe3c
Example Response
{
"response": {
	"ingest_images": [(2)
		{
			"id": 7,
			"ingestable_type": "Container",
			"ingestable_id": 3531,
			"file_path": "the_score_500_375.png",
			"file_size": 623437,
			"state": "done",
			"status": "ok",
			"stage": "archive",
			"message": "processed",
			"iteration": 0,
			"removable_assets": false
		},
		-
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}
							
Notice the status, stage and message fields. The stage field will say which stage the ingest is in right now. The status field will let you know if there is an error while the message field will contain information on that error if there is one.

Example Broken Ingest
{
	"response": {
		"ingest_image": {
			"id": 8,
			"ingestable_type": "Container",
			"ingestable_id": 3531,
			"file_path": "The_score_500_375.png",
			"file_size": null,
			"state": "stopped",
			"status": "error",
			"stage": "harvest",
			"message": "The ingest source file could not be found: The_score_500_375.png",
			"iteration": 0,
			"removable_assets": false
		},
		-
		"code": 1,
		"messages": [(1)
			"Successfully completed."
		]
		-
	}
	-
}