Developer API
Overview
Gomi provides a RESTful API for easy developer integration.
Common use cases:
- Encode videos as they are uploaded to your website
- Bulk encode large video/audio libraries
Security
Users must authenticate by providing a valid API Key. You can manage your api keys
from your account details page.
You're encouraged to connect over SSL (https) so your communications are encrypted.
Typical Workflow
If you were developing a youtube style site:
- User uploads a video that you want to make available in multiple video formats. (e.g High, Medium, Low, iPhone, iPad)
- Create a record in your application for each output format you are intending to deliver
- Call Create Encoding Job method once to create all the encoding jobs, passing in your own CustomerReferenceID's for tracking.
- Receive Job Completion Notifications when video is ready so you can update your application accordingly.
Create Encoding Job
Instructs Gomi to Ingest a video from a url and immediately encode it into one or more output formats. The encoded Output Media can be delivered to your server.
POST
http://api.gomi.com/api/v1/job/create?ApiKey={apikey}
Expected Request Body JSON XML
Host: api.gomi.com
Content-Type: application/json
Content-Length: length
{
"ApiKey":"String", //required
"SourceMediaURL":"String", //required
"OutputJobs":[
{
"OutputFormatID":0, //required
"Title":"String", //optional
"CustomerReferenceID":"String", //optional
"Metadata":"String", //optional
"DeliveryLocation":"String", //optional
"NotificationEmailAddress":"String", //optional
"PingUrl":"String", //optional
"AudioBitrate":128, //optional
"AudioChannelsID":2, //optional
"AudioCodecCode":"String", //optional
"AudioSampleRateID":48000, //optional
"DeInterlace":false, //optional
"FrameRateID":10, //optional
"Width":720, //optional
"Height":576, //optional
"KeepAspectRatio":true, //optional
"VideoResizeMethodCode":"String", //optional
"MediaContainerCode":"String", //optional
"TwoPassEncoding":false, //optional
"VideoBitrate":1024, //optional
"VideoCodecCode":"String" //optional
"OverlayOffsetFrom":"String" //optional
"OverlayImageUri":"String" //optional
"OverlayOffsetX":10 //optional
"OverlayOffsetY":10 //optional
"NewFilename":"String" //optional
"ForcedKeyFrameInterval":0 //optional
"FixedKeyFrameInterval":false //optional
}
]
}
Host: api.gomi.com
Content-Type: application/xml
Content-Length: length
<CreateJob xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ApiKey>String</ApiKey>
<SourceMediaURL>String</SourceMediaURL>
<OutputJobs>
<OutputJobItem>
<OutputFormatID>0</OutputFormatID>
<Title>String</Title>
<CustomerReferenceID>String</CustomerReferenceID>
<Metadata>String</Metadata>
<DeliveryLocation>String</DeliveryLocation>
<PingUrl>String</PingUrl>
<NotificationEmailAddress>String</NotificationEmailAddress>
<AudioBitrate i:nil="true" />
<AudioChannelsID i:nil="true" />
<AudioCodecCode>String</AudioCodecCode>
<AudioSampleRateID i:nil="true" />
<DeInterlace i:nil="true" />
<FrameRateID i:nil="true" />
<Width i:nil="true" />
<Height i:nil="true" />
<KeepAspectRatio i:nil="true" />
<VideoResizeMethodCode>String</VideoResizeMethodCode>
<MediaContainerCode>String</MediaContainerCode>
<TwoPassEncoding i:nil="true" />
<VideoBitrate i:nil="true" />
<VideoCodecCode>String</VideoCodecCode>
<OverlayOffsetFrom>String</OverlayOffsetFrom>
<OverlayImageUri>String</OverlayOffsetUri>
<OverlayOffsetX i:nil="true" />
<OverlayOffsetY i:nil="true" />
<NewFilename>String</NewFilename>
<ForcedKeyFrameInterval i:nil="true" />
<FixedKeyFrameInterval i:nil="true" />
</OutputJobItem>
</OutputJobs>
</CreateJob>
Parameters
{ApiKey}
Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
SourceMediaURL
The URL of the source media file you want to use for encoding. e.g. http://yourserver.com/path/yourfile.avi
Advanced: Gomi supports joining multiple video files together. To use this functionality, just specify multiple Url's separated by the pipe "|" character.
e.g. http://yourserver/yourfile.avi|http://anotherserver/path/anotherfile.wmv
Gomi will automatically import the files in parallel & join them during encoding.
Advanced: Gomi supports joining multiple video files together. To use this functionality, just specify multiple Url's separated by the pipe "|" character.
e.g. http://yourserver/yourfile.avi|http://anotherserver/path/anotherfile.wmv
Gomi will automatically import the files in parallel & join them during encoding.
OutputFormatID
The ID of the predefined OutputFormat that should be used for the base encoding
settings. Any other parameters specified in the request override these base settings.
Manage your account's Output Formats.
Title
You can specify a title for the output media. (Optional)
CustomerReferenceID
You can specify a custom identifier for your own tracking of the file. Typically
the ID of the final media file in your system (Optional)
DeliveryLocation
The ftp location where Gomi should delivery the final encoded media. Expected format:
ftp://[user:password@]yourftpserver.com/[subfolders/] We also have experimental
support for 'ftps' and 'sftp' secure ftp protocols. (Optional)
Metadata
Allows embedding metadata in certain output formats. (For a list of formats & tags
see
MediaWiki FFMPEG Metadata Support)
Accepts a string containing Url encoded key-value pairs of metadata tags in the format: "Key1=Value1&Key2=Value2". This is the same as a standard Url querystring.
e.g. "title=MyTitle&album=MyAlbum" Optional
Accepts a string containing Url encoded key-value pairs of metadata tags in the format: "Key1=Value1&Key2=Value2". This is the same as a standard Url querystring.
e.g. "title=MyTitle&album=MyAlbum" Optional
PingUrl
The Url where you would like webhook notifications sent when the job completes.
(see Job Completion Notification) Optional
NotificationEmailAddress
The email address where you would like job completion notifications sent. This overrides
you account's default notification email address. Optional
MediaContainerCode
Allows overriding the OutputFormat's default Media Container used during encoding.
Optional
Valid Values:
For audio & video: 3g2, 3gp, avi, dvd-ntsc-iso, dvd-ntsc-mpg, dvd-pal-iso, dvd-pal-mpg, fl9, flv, matroska, mov, mp4, mpegts, mxf, ogg, webm, wmv, wmv9
For video only:mjpeg, mpeg2video
For audio only: aac, flac, m4a, mp3, wav, wma
Valid Values:
For audio & video: 3g2, 3gp, avi, dvd-ntsc-iso, dvd-ntsc-mpg, dvd-pal-iso, dvd-pal-mpg, fl9, flv, matroska, mov, mp4, mpegts, mxf, ogg, webm, wmv, wmv9
For video only:mjpeg, mpeg2video
For audio only: aac, flac, m4a, mp3, wav, wma
VideoCodecCode
Allows overriding the OutputFormat's default Video Codec used during encoding.Optional
Valid Values:
copy (copy source stream)
none (no audio)
flv, h263, h264, h264base, huffyuv, libtheora, libvpx, mjpeg, mpeg1video, mpeg2video, mpeg4, mpgNtscDvd, mpgPalDvd, VC-1, VC-1Adv, VC-1Simple, wmv1, wmv2, xvid
Valid Values:
copy (copy source stream)
none (no audio)
flv, h263, h264, h264base, huffyuv, libtheora, libvpx, mjpeg, mpeg1video, mpeg2video, mpeg4, mpgNtscDvd, mpgPalDvd, VC-1, VC-1Adv, VC-1Simple, wmv1, wmv2, xvid
Width
Allows overriding the OutputFormat's default Width (in pixels) used during encoding.Optional
Note, if Width is specified but Height is 0, scales the video to the specified Width while maintaining proportions.
Note, if Width is specified but Height is 0, scales the video to the specified Width while maintaining proportions.
Height
Allows overriding the OutputFormat's default Height (in pixels) used during encoding.Optional
Note, if Height is specified but Width is 0, scales the video to the specified height while maintaining proportions.
Note, if Height is specified but Width is 0, scales the video to the specified height while maintaining proportions.
KeepAspectRatio
Allows overriding the OutputFormat's Keep Aspect Ratio setting used during encoding.
(boolean) Optional
When set to true, attempts to maintain the video's pixel aspect ratio by Cropping and/or Padding the output video. The combination or cropping/padding is controlled by the ResizeMethod parameter.
WMV9 Only: When KeepAspectRatio is true, resizes the video to the largest size that fits within the output Width/Height box while maintaining aspect ratio without cropping or padding.
When set to true, attempts to maintain the video's pixel aspect ratio by Cropping and/or Padding the output video. The combination or cropping/padding is controlled by the ResizeMethod parameter.
WMV9 Only: When KeepAspectRatio is true, resizes the video to the largest size that fits within the output Width/Height box while maintaining aspect ratio without cropping or padding.
VideoBitrate
Allows overriding the OutputFormat's Video Bitrate used during encoding. (in kbps)
Optional
VideoResizeMethodCode
Allows overriding the OutputFormat's Video Resize Method used during encoding. This
setting only applies when KeepAspectRatio is true. Optional
Valid Values:
Auto (Pads a little and Crops a little as necessary to maintain original aspect ratio)
Letterbox (Pads as necessary to maintain original aspect ratio)
PanScan (Crops as necessary to maintain original aspect ratio)
Valid Values:
Auto (Pads a little and Crops a little as necessary to maintain original aspect ratio)
Letterbox (Pads as necessary to maintain original aspect ratio)
PanScan (Crops as necessary to maintain original aspect ratio)
FrameRateID
Allows overriding the OutputFormat's default video Frame Rate used during encoding.
Optional
Valid Values:
-1 (same as source)
10000 (10.0 frames per second)
11988 (11.988 frames per second)
12000 (12.0 frames per second)
14985 (14.985 frames per second)
15000 (15.0 frames per second)
20000 (20.0 frames per second)
23976 (23.976 frames per second)
24000 (24.0 frames per second)
25000 (25.0 frames per second)
29970 (29.97 frames per second)
30000 (30.0 frames per second)
Valid Values:
-1 (same as source)
10000 (10.0 frames per second)
11988 (11.988 frames per second)
12000 (12.0 frames per second)
14985 (14.985 frames per second)
15000 (15.0 frames per second)
20000 (20.0 frames per second)
23976 (23.976 frames per second)
24000 (24.0 frames per second)
25000 (25.0 frames per second)
29970 (29.97 frames per second)
30000 (30.0 frames per second)
AudioCodecCode
Allows overriding the OutputFormat's default Audio Codec used during encoding. Optional
Valid Values:
copy (copy source stream)
none (no audio)
aac, ac3, amr-nb, flac, mp2, mp3, pcm-s16BE, pcm-s16LE, pcm-u8, vorbis, wmaLossless, wmaProfessional, wmaStandard, wmav2, wmaVoice
Valid Values:
copy (copy source stream)
none (no audio)
aac, ac3, amr-nb, flac, mp2, mp3, pcm-s16BE, pcm-s16LE, pcm-u8, vorbis, wmaLossless, wmaProfessional, wmaStandard, wmav2, wmaVoice
AudioBitrate
Allows overriding the OutputFormat's Audio Bitrate used during encoding. (in kbps)
Optional
AudioSampleRateID
Allows overriding the OutputFormat's default audio sample rate used during encoding.
Optional
Valid Values:
-1 (same as source)
8000 (8,000 hz)
11025 (11,025 hz)
16000 (16,000 hz)
22000 (22,000 hz)
22050 (22,050 hz)
24000 (24,000 hz)
32000 (32,000 hz)
44000 (44,000 hz)
44100 (44,100 hz)
48000 (48,000 hz)
192000 (192,000 hz)
Valid Values:
-1 (same as source)
8000 (8,000 hz)
11025 (11,025 hz)
16000 (16,000 hz)
22000 (22,000 hz)
22050 (22,050 hz)
24000 (24,000 hz)
32000 (32,000 hz)
44000 (44,000 hz)
44100 (44,100 hz)
48000 (48,000 hz)
192000 (192,000 hz)
AudioChannelsID
Allows overriding the OutputFormat's default audio channel count used during encoding.
Optional
Valid Values:
1 (Mono)
2 (Stereo)
Valid Values:
1 (Mono)
2 (Stereo)
OverlayOffsetFrom
If applying an overlay image watermark, specifies where the overlay should appear
relative to the underlying video. Optional
Valid values: TopLeft, TopRight, BottomLeft, BottomRight, Center
Valid values: TopLeft, TopRight, BottomLeft, BottomRight, Center
OverlayImageUri
Accepts an http:// url to an image you would like to use as an overlay watermark
over the encoded video. The image can be a png image, and png transparency is supported.
Optional
OverlayOffsetX
Allows customisation of the position of an image watermark. Accepts an integer value
representing the desired horizonal pixel offset from the 'OverlayOffsetFrom' location
Optional
e.g. if OverlayOffsetX = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap to the left of the bottom right corner.
e.g. if OverlayOffsetX = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap to the left of the bottom right corner.
OverlayOffsetY
Allows customisation of the position of an image watermark. Accepts an integer value
representing the desired vertical pixel offset from the 'OverlayOffsetFrom' location
Optional
e.g. if OverlayOffsetY = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap above the bottom right corner.
e.g. if OverlayOffsetY = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap above the bottom right corner.
NewFilename
Allows customization of the base output filename.Optional
Gomi will still append the standard file extension to the value provided here for the specified output media container.
You can also include a few predefined variables:
"[OutputMediaAssetID]" - will be replaced with the Gomi's output media asset ID. e.g "[OutputMediaAssetID]-mynewfilename" will become 42345254-mynewfilename
"[SourceMediaFilename]" - will be replaced with the source filename of the input media.
Gomi by default uses a naming convention of "[OutputMediaAssetID]-[SourceMediaFilename]". The OutputMediaAssetID helps to ensure unique filenames when files are delivered to your server.
Gomi will still append the standard file extension to the value provided here for the specified output media container.
You can also include a few predefined variables:
"[OutputMediaAssetID]" - will be replaced with the Gomi's output media asset ID. e.g "[OutputMediaAssetID]-mynewfilename" will become 42345254-mynewfilename
"[SourceMediaFilename]" - will be replaced with the source filename of the input media.
Gomi by default uses a naming convention of "[OutputMediaAssetID]-[SourceMediaFilename]". The OutputMediaAssetID helps to ensure unique filenames when files are delivered to your server.
ForcedKeyFrameInterval
Allows customization of the KeyFrame intervals when encoding to h.264. Accepts a
positive integer value.
By setting this value you force the encoder to place a keyframe at the specfied frame interval. e.g. specifying 60 forces a keyframe every 60 frames.
You should set this when targetting certain adaptive streaming protocols such as Apple HLS, Microsoft Smooth Streaming & Adobe Dynamic Streaming.
Setting ForcedKeyFrameInterval still allows other key frames to be inserted by the encoder such as at scene changes. This behaviour can be modified by the "FixedKeyFrameInterval" parameter.
By setting this value you force the encoder to place a keyframe at the specfied frame interval. e.g. specifying 60 forces a keyframe every 60 frames.
You should set this when targetting certain adaptive streaming protocols such as Apple HLS, Microsoft Smooth Streaming & Adobe Dynamic Streaming.
Setting ForcedKeyFrameInterval still allows other key frames to be inserted by the encoder such as at scene changes. This behaviour can be modified by the "FixedKeyFrameInterval" parameter.
FixedKeyFrameInterval
For h.264 encoding only. Accepts a true/false value.
Defaults to false. When set to true, does not allow the encoder to insert extra key frames except those specified by the FixedKeyFrameInterval parameter
This is often desirable when targeting the adaptive streaming protocols.
Defaults to false. When set to true, does not allow the encoder to insert extra key frames except those specified by the FixedKeyFrameInterval parameter
This is often desirable when targeting the adaptive streaming protocols.
Response Body JSON XML
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: length
{
"IngestJobID":0,
"IngestJobStatusLocation":"ingest/0",
"InputMediaID":"String",
"OutputJobs":[
{
"JobID":0,
"CustomerReferenceID":"String",
"Success":false,
"JobStatusLocation":"job/0"
}
],
"Success":false,
"ErrorCode":"String",
"Message":"String"
}
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length
<CreateJobResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode>String</ErrorCode>
<Message>String</Message>
<IngestJobID>0</IngestJobID>
<IngestJobStatusLocation>ingest/0</IngestJobStatusLocation>
<InputMediaID>String</InputMediaID>
<OutputJobs>
<JobCreationStatus>
<CustomerReferenceID>String</CustomerReferenceID>
<ErrorCode>String</ErrorCode>
<ErrorMessage>String</ErrorMessage>
<JobID>0</JobID>
<JobStatusLocation>job/0</JobStatusLocation>
<Success>false</Success>
</JobCreationStatus>
</OutputJobs>
<Success>false</Success>
</CreateJobResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Get All Input Media
When you upload or transfer a remote file into Gomi for encoding, it appears as
Input Media.
Input Media is stored temporarily (3 days). Results from this query are paged.
Request
GET
http://api.gomi.com/api/v1/media/input?ApiKey={apikey}
Parameters
{ApiKey}
Querystring parameter - Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
{pageSize}
Querystring parameter used to override the paging size. (Default: 20, Max: 50) (Optional)
{pageNumber}
Specify which page of results to return. (Default: 1) (Optional)
Response JSON XML
{
"InputAssets":[
{
"DateCreatedUTC":"/Date(1329597731598+0000)/",
"DateUpdatedUTC":"/Date(1329597731598+0000)/",
"FileURL":"http://www.gomi.com/download/2/sourcemedia/399/tgwxngv/jkhkj.avi",
"InputMediaID":399,
"MimeType":"video/avi",
"Self":"media/input/399",
"SizeBytes":793340,
"SourceFilename":"jkhkj.avi",
"Status":"available",
"ThumbnailURL":"http://s3-us-west-1.amazonaws.com/gomi-dev1/sourcemedia/399/tgwxngv/399-image00001.jpg",
"Title":"",
"info":{
"AudioTrack":{
"AudioBitrateKbps":64,
"AudioChannelCount":2,
"AudioCodec":"MPEG Audio",
"AudioSampleRateHz":48000
},
"DurationSeconds":19,
"MediaContainerFormat":"AVI",
"TotalBitrateKbps":328,
"VideoTrack":{
"FrameRate":29.969999999999999,
"VideoCodec":"MPEG Audio"
}
}
},
{
"DateCreatedUTC":"/Date(1329596274433+0000)/",
"DateUpdatedUTC":"/Date(1329596274433+0000)/",
"FileURL":"http://www.gomi.com/download/2/sourcemedia/396/ycpgrbo/BMP2_PSP.vob",
"InputMediaID":396,
"MimeType":"video/mpeg",
"Self":"media/input/396",
"SizeBytes":1300480,
"SourceFilename":"BMP2_PSP.vob",
"Status":"available",
"ThumbnailURL":"http://s3-us-west-1.amazonaws.com/gomi-dev1/sourcemedia/396/ycpgrbo/396-image00001.jpg",
"Title":"",
"info":{
"AudioTrack":{
"AudioBitrateKbps":96,
"AudioChannelCount":2,
"AudioCodec":"AC-3",
"AudioSampleRateHz":48000
},
"DurationSeconds":19,
"MediaContainerFormat":"MPEG-PS",
"TotalBitrateKbps":537,
"VideoTrack":{
"FrameRate":29.969999999999999,
"VideoCodec":"AC-3"
}
}
}
],
"PageNumber":1,
"PageSize":20,
"Success":true,
"TotalAssetCount":2,
"ErrorCode":"",
"Message":""
}
<GetInputListResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode i:nil="true" />
<Message i:nil="true" />
<InputAssets>
<InputAsset>
<DateCreatedUTC>2012-02-19T07:42:11.5982317</DateCreatedUTC>
<DateUpdatedUTC>2012-02-19T07:42:11.5982317</DateUpdatedUTC>
<FileURL>http://www.gomi.com/download/2/sourcemedia/399/tgwxngv/jkhkj.avi</FileURL>
<InputMediaID>399</InputMediaID>
<MimeType>video/avi</MimeType>
<Self>media/input/399</Self>
<SizeBytes>793340</SizeBytes>
<SourceFilename>jkhkj.avi</SourceFilename>
<Status>available</Status>
<ThumbnailURL>http://s3-us-west-1.amazonaws.com/gomi-dev1/sourcemedia/399/tgwxngv/399-image00001.jpg</ThumbnailURL>
<Title />
<info>
<AudioTrack>
<AudioBitrateKbps>64</AudioBitrateKbps>
<AudioChannelCount>2</AudioChannelCount>
<AudioCodec>MPEG Audio</AudioCodec>
<AudioSampleRateHz>48000</AudioSampleRateHz>
</AudioTrack>
<DurationSeconds>19</DurationSeconds>
<MediaContainerFormat>AVI</MediaContainerFormat>
<TotalBitrateKbps>328</TotalBitrateKbps>
<VideoTrack>
<FrameRate>29.97000</FrameRate>
<Height i:nil="true" />
<VideoBitrateKbps i:nil="true" />
<VideoCodec>MPEG Audio</VideoCodec>
<Width i:nil="true" />
</VideoTrack>
</info>
</InputAsset>
<InputAsset>
<DateCreatedUTC>2012-02-19T07:17:54.4338866</DateCreatedUTC>
<DateUpdatedUTC>2012-02-19T07:17:54.4338866</DateUpdatedUTC>
<FileURL>http://www.gomi.com/download/2/sourcemedia/396/ycpgrbo/BMP2_PSP.vob</FileURL>
<InputMediaID>396</InputMediaID>
<MimeType>video/mpeg</MimeType>
<Self>media/input/396</Self>
<SizeBytes>1300480</SizeBytes>
<SourceFilename>BMP2_PSP.vob</SourceFilename>
<Status>available</Status>
<ThumbnailURL>http://s3-us-west-1.amazonaws.com/gomi-dev1/sourcemedia/396/ycpgrbo/396-image00001.jpg</ThumbnailURL>
<Title />
<info>
<AudioTrack>
<AudioBitrateKbps>96</AudioBitrateKbps>
<AudioChannelCount>2</AudioChannelCount>
<AudioCodec>AC-3</AudioCodec>
<AudioSampleRateHz>48000</AudioSampleRateHz>
</AudioTrack>
<DurationSeconds>19</DurationSeconds>
<MediaContainerFormat>MPEG-PS</MediaContainerFormat>
<TotalBitrateKbps>537</TotalBitrateKbps>
<VideoTrack>
<FrameRate>29.97000</FrameRate>
<Height i:nil="true" />
<VideoBitrateKbps i:nil="true" />
<VideoCodec>AC-3</VideoCodec>
<Width i:nil="true" />
</VideoTrack>
</info>
</InputAsset>
</InputAssets>
<PageNumber>1</PageNumber>
<PageSize>20</PageSize>
<Success>true</Success>
<TotalAssetCount>2</TotalAssetCount>
</GetInputListResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Get Input Item
Retrieves the metadata for an individual input asset.
Request
GET
http://api.gomi.com/api/v1/media/input/{InputMediaID}?ApiKey={apikey}&format={json|xml}
Parameters
{InputMediaID}
The ID of the Input Media.
{ApiKey}
Querystring parameter - Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
Response JSON XML
{
"asset":
{
"DateCreatedUTC":"/Date(1329597731598+0000)/",
"DateUpdatedUTC":"/Date(1329597731598+0000)/",
"FileURL":"http://www.gomi.com/download/2/sourcemedia/399/tgwxngv/jkhkj.avi",
"InputMediaID":399,
"MimeType":"video/avi",
"Self":"media/input/399",
"SizeBytes":793340,
"SourceFilename":"jkhkj.avi",
"Status":"available",
"ThumbnailURL":"http://s3-us-west-1.amazonaws.com/gomi-dev1/sourcemedia/399/tgwxngv/399-image00001.jpg",
"Title":"",
"info":{
"AudioTrack":{
"AudioBitrateKbps":64,
"AudioChannelCount":2,
"AudioCodec":"MPEG Audio",
"AudioSampleRateHz":48000
},
"DurationSeconds":19,
"MediaContainerFormat":"AVI",
"TotalBitrateKbps":328,
"VideoTrack":{
"FrameRate":29.969999999999999,
"VideoCodec":"MPEG Audio"
}
}
},
"Success":true,
"ErrorCode":"",
"Message":""
}
<GetInputItemResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode i:nil="true" />
<Message i:nil="true" />
<InputAsset>
<DateCreatedUTC>2012-02-19T07:42:11.5982317</DateCreatedUTC>
<DateUpdatedUTC>2012-02-19T07:42:11.5982317</DateUpdatedUTC>
<FileURL>http://www.gomi.com/download/2/sourcemedia/399/tgwxngv/jkhkj.avi</FileURL>
<InputMediaID>399</InputMediaID>
<MimeType>video/avi</MimeType>
<Self>media/input/399</Self>
<SizeBytes>793340</SizeBytes>
<SourceFilename>jkhkj.avi</SourceFilename>
<Status>available</Status>
<ThumbnailURL>http://s3-us-west-1.amazonaws.com/gomi-dev1/sourcemedia/399/tgwxngv/399-image00001.jpg</ThumbnailURL>
<Title />
<info>
<AudioTrack>
<AudioBitrateKbps>64</AudioBitrateKbps>
<AudioChannelCount>2</AudioChannelCount>
<AudioCodec>MPEG Audio</AudioCodec>
<AudioSampleRateHz>48000</AudioSampleRateHz>
</AudioTrack>
<DurationSeconds>19</DurationSeconds>
<MediaContainerFormat>AVI</MediaContainerFormat>
<TotalBitrateKbps>328</TotalBitrateKbps>
<VideoTrack>
<FrameRate>29.97000</FrameRate>
<Height i:nil="true" />
<VideoBitrateKbps i:nil="true" />
<VideoCodec>MPEG Audio</VideoCodec>
<Width i:nil="true" />
</VideoTrack>
</info>
</InputAsset>
<Success>true</Success>
</GetInputItemResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Get All Output Media
Encoded videos are stored temporarily (2 days) by Gomi, and appear in Output Media.
Results from this query are paged.
Request
GET
http://api.gomi.com/api/v1/media/output?ApiKey={apikey}&format={json|xml}
Parameters
{ApiKey}
Querystring parameter - Your developer Api Key.
{format}
(Optional) Querystring parameter used to Override the response format specified
in the HTTP Accept header. Valid values are xml or
are json
{pageSize}
(Optional) Querystring parameter used to override the paging size. (Default: 20,
Max: 50)
{pageNumber}
(optional) Specify which page of results to return. (Default: 1)
Response JSON XML
{
"TotalAssetCount":9,
"PageSize":2,
"PageNumber":1,
"OutputAssets":[
{
"OutputMediaID":63119,
"Title":"Sample Video",
"SizeBytes":2288718,
"Status":"available",
"ThumbnailURL":"http://s3-us-west-1.amazonaws.com/gomi-test/output/63119/vzggdak/63119-image00001.jpg",
"FileURL":"http://test.gomi.com/download/3/output/63119/vzggdak/63119-hybla-fair.mp4",
"Filename":"63119-hybla-fair.mp4",
"DateCreatedUTC":"\/Date(1329543335793+0000)\/",
"DateUpdatedUTC":"\/Date(1329542969571+0000)\/",
"info":{
"MediaContainerFormat":"MPEG-4",
"TotalBitrateKbps":502,
"DurationSeconds":36,
"VideoTrack":{
"VideoCodec":"AAC",
"FrameRate":15.00000
},
"AudioTrack":{
"AudioCodec":"AAC",
"AudioSampleRateHz":24000,
"AudioChannelCount":2,
"AudioBitrateKbps":96
}
},
"Self":"media/output/63119"
},
{
"OutputMediaID":63118,
"Title":"Another Sample",
"SizeBytes":20031967,
"Status":"available",
"ThumbnailURL":"http://s3-us-west-1.amazonaws.com/gomi-test/output/63118/qhpdiwx/63118-image00001.jpg",
"FileURL":"http://test.gomi.com/download/3/output/63118/qhpdiwx/63118-FCL_1080p.mp4",
"Filename":"63118-FCL_1080p.mp4",
"DateCreatedUTC":"\/Date(1329297178890+0000)\/",
"DateUpdatedUTC":"\/Date(1329297098610+0000)\/",
"info":{
"MediaContainerFormat":"MPEG-4",
"TotalBitrateKbps":2217,
"DurationSeconds":72,
"VideoTrack":{
"VideoCodec":"AAC",
"FrameRate":23.97600
},
"AudioTrack":{
"AudioCodec":"AAC",
"AudioSampleRateHz":48000,
"AudioChannelCount":2,
"AudioBitrateKbps":160
}
},
"Self":"media/output/63118"
}
],
"Success":true,
"ErrorCode":"",
"Message":""
}
<GetOutputListResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode i:nil="true" />
<Message i:nil="true" />
<OutputAssets>
<OutputAsset>
<DateCreatedUTC>2012-02-18T05:35:35.793</DateCreatedUTC>
<DateUpdatedUTC>2012-02-18T05:29:29.5719226</DateUpdatedUTC>
<FileURL>http://test.gomi.com/download/3/output/63119/vzggdak/63119-hybla-fair.mp4</FileURL>
<Filename>63119-hybla-fair.mp4</Filename>
<OutputMediaID>63119</OutputMediaID>
<Self>media/output/63119</Self>
<SizeBytes>2288718</SizeBytes>
<Status>available</Status>
<ThumbnailURL>http://s3-us-west-1.amazonaws.com/gomi-test/output/63119/vzggdak/63119-image00001.jpg</ThumbnailURL>
<Title>test import</Title>
<info>
<AudioTrack>
<AudioBitrateKbps>96</AudioBitrateKbps>
<AudioChannelCount>2</AudioChannelCount>
<AudioCodec>AAC</AudioCodec>
<AudioSampleRateHz>24000</AudioSampleRateHz>
</AudioTrack>
<DurationSeconds>36</DurationSeconds>
<MediaContainerFormat>MPEG-4</MediaContainerFormat>
<TotalBitrateKbps>502</TotalBitrateKbps>
<VideoTrack>
<FrameRate>15.00000</FrameRate>
<Height i:nil="true" />
<VideoBitrateKbps i:nil="true" />
<VideoCodec>AAC</VideoCodec>
<Width i:nil="true" />
</VideoTrack>
</info>
</OutputAsset>
<OutputAsset>
<DateCreatedUTC>2012-02-15T09:12:58.89</DateCreatedUTC>
<DateUpdatedUTC>2012-02-15T09:11:38.6103901</DateUpdatedUTC>
<FileURL>http://test.gomi.com/download/3/output/63118/qhpdiwx/63118-FCL_1080p.mp4</FileURL>
<Filename>63118-FCL_1080p.mp4</Filename>
<OutputMediaID>63118</OutputMediaID>
<Self>media/output/63118</Self>
<SizeBytes>20031967</SizeBytes>
<Status>available</Status>
<ThumbnailURL>http://s3-us-west-1.amazonaws.com/gomi-test/output/63118/qhpdiwx/63118-image00001.jpg</ThumbnailURL>
<Title>sample</Title>
<info>
<AudioTrack>
<AudioBitrateKbps>160</AudioBitrateKbps>
<AudioChannelCount>2</AudioChannelCount>
<AudioCodec>AAC</AudioCodec>
<AudioSampleRateHz>48000</AudioSampleRateHz>
</AudioTrack>
<DurationSeconds>72</DurationSeconds>
<MediaContainerFormat>MPEG-4</MediaContainerFormat>
<TotalBitrateKbps>2217</TotalBitrateKbps>
<VideoTrack>
<FrameRate>23.97600</FrameRate>
<Height i:nil="true" />
<VideoBitrateKbps i:nil="true" />
<VideoCodec>AAC</VideoCodec>
<Width i:nil="true" />
</VideoTrack>
</info>
</OutputAsset>
</OutputAssets>
<PageNumber>1</PageNumber>
<PageSize>2</PageSize>
<Success>true</Success>
<TotalAssetCount>9</TotalAssetCount>
</GetOutputListResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Get Output Item
Get the details for an individual output media asset.
Request
GET
http://api.gomi.com/api/v1/media/output/{OutputMediaID}?ApiKey={apikey}&format={json|xml}
Parameters
{ApiKey}
Querystring parameter - Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
Response JSON XML
{
"asset":{
"OutputMediaID":63119,
"Title":"test import",
"SizeBytes":2288718,
"Status":"available",
"ThumbnailURL":"http://s3-us-west-1.amazonaws.com/gomi-test/output/63119/vzggdak/63119-image00001.jpg",
"FileURL":"http://test.gomi.com/download/3/output/63119/vzggdak/63119-hybla-fair.mp4",
"Filename":"63119-hybla-fair.mp4",
"DateCreatedUTC":"\/Date(1329543335793+0000)\/",
"DateUpdatedUTC":"\/Date(1329542969571+0000)\/",
"info":{
"MediaContainerFormat":"MPEG-4",
"TotalBitrateKbps":502,
"DurationSeconds":36,
"VideoTrack":{
"VideoCodec":"AAC",
"FrameRate":15.00000
},
"AudioTrack":{
"AudioCodec":"AAC",
"AudioSampleRateHz":24000,
"AudioChannelCount":2,
"AudioBitrateKbps":96
}
},
"Self":"media/output/63119"
},
"Success":true,
"ErrorCode":"",
"Message":""
}
<GetOutputItemResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode i:nil="true" />
<Message i:nil="true" />
<Success>true</Success>
<asset>
<DateCreatedUTC>2012-02-18T05:35:35.793</DateCreatedUTC>
<DateUpdatedUTC>2012-02-18T05:29:29.5719226</DateUpdatedUTC>
<FileURL>http://test.gomi.com/download/3/output/63119/vzggdak/63119-hybla-fair.mp4</FileURL>
<Filename>63119-hybla-fair.mp4</Filename>
<OutputMediaID>63119</OutputMediaID>
<Self>media/output/63119</Self>
<SizeBytes>2288718</SizeBytes>
<Status>available</Status>
<ThumbnailURL>http://s3-us-west-1.amazonaws.com/gomi-test/output/63119/vzggdak/63119-image00001.jpg</ThumbnailURL>
<Title>test import</Title>
<info>
<AudioTrack>
<AudioBitrateKbps>96</AudioBitrateKbps>
<AudioChannelCount>2</AudioChannelCount>
<AudioCodec>AAC</AudioCodec>
<AudioSampleRateHz>24000</AudioSampleRateHz>
</AudioTrack>
<DurationSeconds>36</DurationSeconds>
<MediaContainerFormat>MPEG-4</MediaContainerFormat>
<TotalBitrateKbps>502</TotalBitrateKbps>
<VideoTrack>
<FrameRate>15.00000</FrameRate>
<Height i:nil="true" />
<VideoBitrateKbps i:nil="true" />
<VideoCodec>AAC</VideoCodec>
<Width i:nil="true" />
</VideoTrack>
</info>
</asset>
</GetOutputItemResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Job Completion Notification
When a job completes, whether successfully or unsuccessfully, your app can receive a notification of the outcome. This allows you to update your database, send notifications to your users etc.
Job Notifications follow the 'webhook' convention. They are basic form-urlencoded http post requests made to the URL of your choice. You can set a default ping url in your account settings. You can also override the ping url when you create a job via the api.
HTTP POST Notification Format
POST your_ping_url HTTP/1.1
Content-Type: application/x-www-form-urlencoded
JobID=1234&JobType=Encoding&Result=Success&FileName=your-encoded0-file.mp4&ErrorCode=&ErrorMessage=&
DownloadURL=http%3a%2f%2fgomi.com%2fdownload%2fyour-encoded0-file.mp4&OutputMediaID=14435&CustomerReferenceID=a4tg3fwe
Posted Fields
JobID
Gomi's ID for the job
JobType
The type of Job. Valid values include Encoding or
Ingest
Result
The job completion status: Success or
JobError
ErrorCode
The error code associated with a JobError result.
ErrorMessage
The description of the error
FileName
The filename assigned by Gomi to the output file. This is the filename that will
appear on your servers if you chose to have the file delivered.
InputMediaID
Gomi's ID for the ingested input media. This can be used to query gomi's api to
obtain input media metadata.
DownloadURL
The temporary OutputMedia Download URL where you can download the file. (Encoding
Jobs Only)
OutputMediaID
Gomi's ID for the OutputMedia asset. You can use this to query Gomi's api for further
information about the asset. (Encoding Jobs Only)
CustomerReferenceID
For ingest jobs, the CustomerReferenceID you provided for the input media.
For encoding jobs, the CustomerReferenceID you provided for the output when creating the job.
For encoding jobs, the CustomerReferenceID you provided for the output when creating the job.
Get Active Encoding Jobs
Returns information about all your active encoding jobs.
Results from this query are paged.
Request
GET
http://api.gomi.com/api/v1/job/active?ApiKey={apikey}
Parameters
{ApiKey}
Querystring parameter - Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
{pageSize}
Querystring parameter used to override the paging size. (Default: 20, Max: 50) (Optional)
{pageNumber}
Specify which page of results to return. (Default: 1) (Optional)
Response JSON XML
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: length
{
"TotalItemCount":1,
"PageSize":20,
"PageNumber":1,
"jobs":[
{
"JobID":63070,
"ThumbnailURL":"http://images.gomi.com/sourcemedia/400/bapegvd/400-image00001.jpg",
"StartedMinutesAgo":0,
"MediaTitle":"",
"Status":"Encoding",
"ImportingProgress":100,
"EncodingProgress":30,
"StoringProgress":0,
"DistributionProgress":0,
"DateCreatedUTC":"\/Date(1331018014070+0000)\/",
"DateUpdatedUTC":"\/Date(1331018014070+0000)\/",
"Self":"job/63070"
}
],
"Success":true,
"ErrorCode":"",
"Message":""
}
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length
<GetActiveJobsResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode i:nil="true" />
<Message i:nil="true" />
<PageNumber>1</PageNumber>
<PageSize>20</PageSize>
<Success>true</Success>
<TotalItemCount>1</TotalItemCount>
<jobs>
<JobStatusItem>
<DateCreatedUTC>2012-03-06T07:13:34.07</DateCreatedUTC>
<DateUpdatedUTC>2012-03-06T07:13:34.07</DateUpdatedUTC>
<DistributionProgress>0</DistributionProgress>
<EncodingProgress>30</EncodingProgress>
<ErrorCode i:nil="true" />
<ErrorMessage i:nil="true" />
<ImportingProgress>100</ImportingProgress>
<JobID>63070</JobID>
<MediaTitle />
<Self>job/63070</Self>
<StartedMinutesAgo>3</StartedMinutesAgo>
<Status>Encoding</Status>
<StoringProgress>0</StoringProgress>
<ThumbnailURL>http://images.gomi.com/sourcemedia/400/bapegvd/400-image00001.jpg</ThumbnailURL>
</JobStatusItem>
</jobs>
</GetActiveJobsResponse>
Response fields
Success
Whether the request was successful or not. (boolean)
ErrorCode
The error code associated with an unsuccessful result.
ErrorMessage
The description of the error
TotalItemCount
The total number of active jobs
PageSize
The number of items currently being returned per page.
PageNumber
The number of the current page. Page numbers start from 1.
DateCreatedUTC
The date & time that the job was started expressed as milliseconds since midnight
1/Jan/1970 in Coordianted Universal Time (UTC).
DateUpdatedUTC
The date & time that the job was last updated expressed as milliseconds since midnight
1/Jan/1970 in Coordianted Universal Time (UTC).
JobID
Gomi's unique ID for the Job.
ThumbnailURL
The URL of the thumbnail generated by Gomi from the input media. This is only stored
temporarily by Gomi.
JobStatus
The current status of the encoding job. Valid statuses are: WaitingForMediaImport,AddingToQueueAddedToQueue,
LoadingMedia,EncodingMedia,StoringMedia,DeliveringMedia,
Complete, JobError
ImportProgress
The percentage progress made in loading the video file to the encoding server. Represented
as integer values between 0 and 100.
EncodingProgress
The percentage progess made in encoding the video file. Represented as integer values
between 0 and 100.
StoringProgress
The percentage progress made in storing the output file in Gomi storage. Represented
as integer values between 0 and 100.
DistributionProgress
If you requested Delivery of the output file to your server, this value is the percentage
progress made in delivery.
MediaTitle
The user provided title for the media file
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Create Ingest Job
Instructs Gomi to Ingest a video from a web or ftp server. You can optionally receive
an API notification when the ingest process is completed.
This method is maintly used if you want to split up the encoding process into two
steps; ingest then encoding, allowing you the flexibility to customise your encoding
request based on the input asset's metadata.
POST
http://api.gomi.com/api/v1/ingest/create?ApiKey={apikey}
Expected Request Body JSON XML
Host: api.gomi.com
Content-Type: application/json
Content-Length: length
{
"ApiKey":"String", //required
"SourceMediaURL":"String", //required
"title","String", //optional
"CustomerReferenceID":"String" //optional
}
Host: api.gomi.com
Content-Type: application/xml
Content-Length: length
<CreateIngest xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ApiKey>String</ApiKey>
<SourceMediaURL>String</SourceMediaURL>
<title>String</title>
<CustomerReferenceID>String</CustomerReferenceID>
</CreateIngest>
Parameters
{ApiKey}
Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
SourceMediaURL
The FTP or WebServer URI of the source media file you want to use for encoding.
e.g. http://yourserver.com/path/yourfile.avi or ftp://user:password@yourserver.com/path/yourfile.avi
Title
You can specify a title for the input media. (Optional)
CustomerReferenceID
You can specify a custom identifier for your own tracking of the file. Typically
the ID of the media file in your system (Optional)
Response Body JSON XML
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: length
{
"IngestJobID":0,
"IngestJobStatusLocation":"ingest/0",
"CustomerReferenceID","String",
"InputMediaID":0,
"Success":false,
"ErrorCode":"String",
"Message":"String"
}
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length
<CreateIngestResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<IngestJobID>0</IngestJobID>
<IngestJobStatusLocation>ingest/0</IngestJobStatusLocation>
<CustomerReferenceID>String</CustomerReferenceID>
<InputMediaID>0</InputMediaID>
<ErrorCode>String</ErrorCode>
<Message>String</Message>
<Success>false</Success>
</CreateJobResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.
Get Active Ingests
Returns information about all your active ingest jobs.
Results from this query are paged.
Request
GET
http://api.gomi.com/api/v1/ingest/active?ApiKey={apikey}
Parameters
{ApiKey}
Querystring parameter - Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
{pageSize}
Querystring parameter used to override the paging size. (Default: 20, Max: 50) (Optional)
{pageNumber}
Specify which page of results to return. (Default: 1) (Optional)
Response JSON XML
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: length
{
"TotalItemCount":1,
"PageSize":20,
"PageNumber":1,
"ingests":[
{
"IngestID":388,
"StartedMinutesAgo":2,
"Title":"Sample Video",
"IngestStatus":"AddedToQueue",
"SizeBytes":46249993,
"PrettySize":"44.11 MB",
"MimeType":"video/mp4",
"TransferProgress":0,
"StoringProgress":0,
"InputMediaID":0,
"DateCreatedUTC":"\/Date(1331031213379+0000)\/",
"DateUpdatedUTC":"\/Date(1331031213379+0000)\/",
"Self":"ingest/388"
}
],
"Success":true,
"ErrorCode":"",
"Message":""
}
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length
<GetActiveIngestsResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ErrorCode i:nil="true" />
<Message i:nil="true" />
<PageNumber>1</PageNumber>
<PageSize>20</PageSize>
<Success>true</Success>
<TotalItemCount>1</TotalItemCount>
<ingests>
<IngestStatusItem>
<DateCreatedUTC>2012-03-06T10:53:33.3796312</DateCreatedUTC>
<DateUpdatedUTC>2012-03-06T10:53:33.3796312</DateUpdatedUTC>
<ErrorCode i:nil="true" />
<ErrorMessage i:nil="true" />
<IngestID>388</IngestID>
<IngestStatus>AddedToQueue</IngestStatus>
<InputMediaID>0</InputMediaID>
<MimeType>video/mp4</MimeType>
<PrettySize>44.11 MB</PrettySize>
<RemoteURL i:nil="true" />
<Self>ingest/388</Self>
<SizeBytes>46249993</SizeBytes>
<StartedMinutesAgo>1</StartedMinutesAgo>
<StoringProgress>0</StoringProgress>
<Title>Sample Video</Title>
<TransferProgress>0</TransferProgress>
</IngestStatusItem>
</ingests>
</GetActiveIngestsResponse>
Response fields
Success
Whether the request was successful or not. (boolean)
ErrorCode
The error code associated with an unsuccessful result.
ErrorMessage
The description of the error
TotalItemCount
The total number of active jobs
PageSize
The number of items currently being returned per page.
PageNumber
The number of the current page. Page numbers start from 1.
DateCreatedUTC
The date & time that the ingest job was started expressed as milliseconds since
midnight 1/Jan/1970 in Coordianted Universal Time (UTC).
DateUpdatedUTC
The date & time that the ingest job was last updated expressed as milliseconds since
midnight 1/Jan/1970 in Coordianted Universal Time (UTC).
IngestID
Gomi's unique ID for the Ingest Job.
InputMediaID
The ID Gomi will apply to the input media once it has been transferred into Gomi.
MimeType
The MimeType/ContentType of the media file as reported by its originating server
SizeBytes
The size in bytes of the file being transferred.
PrettySize
The size of the file being transferred. Formatted for ease of readibility
RemoteURL
After any redirects are followed, the final url where the file is being transferred
from.
IngestStatus
The current status of the ingest job. Valid statuses are: RemoteFileVerified,
AddedToQueue, ImportingMedia,
StoringMedia, Complete,
IngestError
TransferProgress
The percentage progress made in transferring the file in from a remote server. Represented
as integer values between 0 and 100.
StoringProgress
The percentage progress made in storing the input file in Gomi storage. Represented
as integer values between 0 and 100.
Title
The user provided title for the media file
StartedMinutesAgo
The number of minutes that have elapsed since the ingest job was started
Create Encoding Job from Input Media
Instructs Gomi to create jobs to encode already ingested Input Media into one or more output formats. The encoded Output Media can be delivered to your server & API Notifications sent on completion.
POST
http://api.gomi.com/api/v1/job/CreateJobFromInputMedia?ApiKey={apikey}
Expected Request Body JSON XML
Host: api.gomi.com
Content-Type: application/json
Content-Length: length
{
"ApiKey":"String", //required
"InputMediaID":"String", //required
"OutputJobs":[
{
"OutputFormatID":0, //required
"Title":"String", //optional
"CustomerReferenceID":"String", //optional
"DeliveryLocation":"String", //optional
"NotificationEmailAddress":"String", //optional
"Metadata":"String", //optional
"PingUrl":"String", //optional
"AudioBitrate":128, //optional
"AudioChannelsID":2, //optional
"AudioCodecCode":"String", //optional
"AudioSampleRateID":48000, //optional
"DeInterlace":false, //optional
"FrameRateID":10, //optional
"Width":720, //optional
"Height":576, //optional
"KeepAspectRatio":true, //optional
"VideoResizeMethodCode":"String", //optional
"MediaContainerCode":"String", //optional
"TwoPassEncoding":false, //optional
"VideoBitrate":1024, //optional
"VideoCodecCode":"String" //optional
"OverlayOffsetFrom":"String" //optional
"OverlayImageUri":"String" //optional
"OverlayOffsetX":10 //optional
"OverlayOffsetY":10 //optional
"NewFilename":"String" //optional
"ForcedKeyFrameInterval":0 //optional
"FixedKeyFrameInterval":false //optional
}
]
}
Host: api.gomi.com
Content-Type: application/xml
Content-Length: length
<CreateJobFromInputMedia xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<ApiKey>String</ApiKey>
<InputMediaID>String</InputMediaID>
<OutputJobs>
<OutputJobItem>
<OutputFormatID>0</OutputFormatID>
<Title>String</Title>
<CustomerReferenceID>String</CustomerReferenceID>
<DeliveryLocation>String</DeliveryLocation>
<Metadata>String</Metadata>
<PingUrl>String</PingUrl>
<NotificationEmailAddress>String</NotificationEmailAddress>
<AudioBitrate i:nil="true" />
<AudioChannelsID i:nil="true" />
<AudioCodecCode>String</AudioCodecCode>
<AudioSampleRateID i:nil="true" />
<DeInterlace i:nil="true" />
<FrameRateID i:nil="true" />
<Width i:nil="true" />
<Height i:nil="true" />
<KeepAspectRatio i:nil="true" />
<VideoResizeMethodCode>String</VideoResizeMethodCode>
<MediaContainerCode>String</MediaContainerCode>
<TwoPassEncoding i:nil="true" />
<VideoBitrate i:nil="true" />
<VideoCodecCode>String</VideoCodecCode>
<OverlayOffsetFrom>String</OverlayOffsetFrom>
<OverlayImageUri>String</OverlayOffsetUri>
<OverlayOffsetX i:nil="true" />
<OverlayOffsetY i:nil="true" />
<NewFilename>String</NewFilename>
<ForcedKeyFrameInterval i:nil="true" />
<FixedKeyFrameInterval i:nil="true" />
</OutputJobItem>
</OutputJobs>
</CreateJob>
Parameters
{ApiKey}
Your developer Api Key.
{format}
Querystring parameter used to Override the response format specified in the HTTP
Accept header. Valid values are xml or are
json (Optional)
InputMediaID
The ID of the previously ingested Input Media that you want to use for encoding.
Advanced: Gomi supports joining multiple video files together. To use this functionality, just specify multiple InputMediaID's separated by the pipe "|" character.
e.g. "30023|31063|12086"
Gomi will automatically join them during encoding.
Advanced: Gomi supports joining multiple video files together. To use this functionality, just specify multiple InputMediaID's separated by the pipe "|" character.
e.g. "30023|31063|12086"
Gomi will automatically join them during encoding.
OutputFormatID
The ID of the predefined OutputFormat that should be used for the base encoding
settings. Any other parameters specified in the request override these base settings.
Manage your account's Output Formats.
Title
You can specify a title for the output media. (Optional)
CustomerReferenceID
You can specify a custom identifier for your own tracking of the file. Typically
the ID of the final media file in your system (Optional)
DeliveryLocation
The ftp location where Gomi should delivery the final encoded media. Expected format:
ftp://[user:password@]yourftpserver.com/[subfolders/] We also have experimental
support for 'ftps' and 'sftp' secure ftp protocols. (Optional)
Metadata
Allows embedding metadata in certain output formats. (For a list of formats & tags
see
MediaWiki FFMPEG Metadata Support)
Accepts a string containing Url encoded key-value pairs of metadata tags in the format: "Key1=Value1&Key2=Value2". This is the same as a standard Url querystring.
e.g. "title=MyTitle&album=MyAlbum" Optional
Accepts a string containing Url encoded key-value pairs of metadata tags in the format: "Key1=Value1&Key2=Value2". This is the same as a standard Url querystring.
e.g. "title=MyTitle&album=MyAlbum" Optional
PingUrl
The Url where you would like webhook notifications sent when the job completes.
(see Job Completion Notification) Optional
NotificationEmailAddress
The email address where you would like job completion notifications sent. This overrides
you account's default notification email address. Optional
MediaContainerCode
Allows overriding the OutputFormat's default Media Container used during encoding.
Optional
Valid Values:
For audio & video: 3g2, 3gp, avi, dvd-ntsc-iso, dvd-ntsc-mpg, dvd-pal-iso, dvd-pal-mpg, fl9, flv, matroska, mov, mp4, mpegts, mxf, ogg, webm, wmv, wmv9
For video only:mjpeg, mpeg2video
For audio only: aac, flac, m4a, mp3, wav, wma
Valid Values:
For audio & video: 3g2, 3gp, avi, dvd-ntsc-iso, dvd-ntsc-mpg, dvd-pal-iso, dvd-pal-mpg, fl9, flv, matroska, mov, mp4, mpegts, mxf, ogg, webm, wmv, wmv9
For video only:mjpeg, mpeg2video
For audio only: aac, flac, m4a, mp3, wav, wma
VideoCodecCode
Allows overriding the OutputFormat's default Video Codec used during encoding.Optional
Valid Values:
copy (copy source stream)
none (no audio)
flv, h263, h264, h264base, huffyuv, libtheora, libvpx, mjpeg, mpeg1video, mpeg2video, mpeg4, mpgNtscDvd, mpgPalDvd, VC-1, VC-1Adv, VC-1Simple, wmv1, wmv2, xvid
Valid Values:
copy (copy source stream)
none (no audio)
flv, h263, h264, h264base, huffyuv, libtheora, libvpx, mjpeg, mpeg1video, mpeg2video, mpeg4, mpgNtscDvd, mpgPalDvd, VC-1, VC-1Adv, VC-1Simple, wmv1, wmv2, xvid
Width
Allows overriding the OutputFormat's default Width (in pixels) used during encoding.Optional
Note, if Width is specified but Height is 0, scales the video to the specified Width while maintaining proportions.
Note, if Width is specified but Height is 0, scales the video to the specified Width while maintaining proportions.
Height
Allows overriding the OutputFormat's default Height (in pixels) used during encoding.Optional
Note, if Height is specified but Width is 0, scales the video to the specified height while maintaining proportions.
Note, if Height is specified but Width is 0, scales the video to the specified height while maintaining proportions.
KeepAspectRatio
Allows overriding the OutputFormat's Keep Aspect Ratio setting used during encoding.
(boolean) Optional
When set to true, attempts to maintain the video's pixel aspect ratio by Cropping and/or Padding the output video. The combination or cropping/padding is controlled by the ResizeMethod parameter.
WMV9 Only: When KeepAspectRatio is true, resizes the video to the largest size that fits within the output Width/Height box while maintaining aspect ratio without cropping or padding.
When set to true, attempts to maintain the video's pixel aspect ratio by Cropping and/or Padding the output video. The combination or cropping/padding is controlled by the ResizeMethod parameter.
WMV9 Only: When KeepAspectRatio is true, resizes the video to the largest size that fits within the output Width/Height box while maintaining aspect ratio without cropping or padding.
VideoBitrate
Allows overriding the OutputFormat's Video Bitrate used during encoding. (in kbps)
Optional
VideoResizeMethodCode
Allows overriding the OutputFormat's Video Resize Method used during encoding. This
setting only applies when KeepAspectRatio is true. Optional
Valid Values:
Auto (Pads a little and Crops a little as necessary to maintain original aspect ratio)
Letterbox (Pads as necessary to maintain original aspect ratio)
PanScan (Crops as necessary to maintain original aspect ratio)
Valid Values:
Auto (Pads a little and Crops a little as necessary to maintain original aspect ratio)
Letterbox (Pads as necessary to maintain original aspect ratio)
PanScan (Crops as necessary to maintain original aspect ratio)
FrameRateID
Allows overriding the OutputFormat's default video Frame Rate used during encoding.
Optional
Valid Values:
-1 (same as source)
10000 (10.0 frames per second)
11988 (11.988 frames per second)
12000 (12.0 frames per second)
14985 (14.985 frames per second)
15000 (15.0 frames per second)
20000 (20.0 frames per second)
23976 (23.976 frames per second)
24000 (24.0 frames per second)
25000 (25.0 frames per second)
29970 (29.97 frames per second)
30000 (30.0 frames per second)
Valid Values:
-1 (same as source)
10000 (10.0 frames per second)
11988 (11.988 frames per second)
12000 (12.0 frames per second)
14985 (14.985 frames per second)
15000 (15.0 frames per second)
20000 (20.0 frames per second)
23976 (23.976 frames per second)
24000 (24.0 frames per second)
25000 (25.0 frames per second)
29970 (29.97 frames per second)
30000 (30.0 frames per second)
AudioCodecCode
Allows overriding the OutputFormat's default Audio Codec used during encoding. Optional
Valid Values:
copy (copy source stream)
none (no audio)
aac, ac3, amr-nb, flac, mp2, mp3, pcm-s16BE, pcm-s16LE, pcm-u8, vorbis, wmaLossless, wmaProfessional, wmaStandard, wmav2, wmaVoice
Valid Values:
copy (copy source stream)
none (no audio)
aac, ac3, amr-nb, flac, mp2, mp3, pcm-s16BE, pcm-s16LE, pcm-u8, vorbis, wmaLossless, wmaProfessional, wmaStandard, wmav2, wmaVoice
AudioBitrate
Allows overriding the OutputFormat's Audio Bitrate used during encoding. (in kbps)
Optional
AudioSampleRateID
Allows overriding the OutputFormat's default audio sample rate used during encoding.
Optional
Valid Values:
-1 (same as source)
8000 (8,000 hz)
11025 (11,025 hz)
16000 (16,000 hz)
22000 (22,000 hz)
22050 (22,050 hz)
24000 (24,000 hz)
32000 (32,000 hz)
44000 (44,000 hz)
44100 (44,100 hz)
48000 (48,000 hz)
192000 (192,000 hz)
Valid Values:
-1 (same as source)
8000 (8,000 hz)
11025 (11,025 hz)
16000 (16,000 hz)
22000 (22,000 hz)
22050 (22,050 hz)
24000 (24,000 hz)
32000 (32,000 hz)
44000 (44,000 hz)
44100 (44,100 hz)
48000 (48,000 hz)
192000 (192,000 hz)
AudioChannelsID
Allows overriding the OutputFormat's default audio channel count used during encoding.
Optional
Valid Values:
1 (Mono)
2 (Stereo)
Valid Values:
1 (Mono)
2 (Stereo)
OverlayOffsetFrom
If applying an overlay image watermark, specifies where the overlay should appear
relative to the underlying video. Optional
Valid values: TopLeft, TopRight, BottomLeft, BottomRight, Center
Valid values: TopLeft, TopRight, BottomLeft, BottomRight, Center
OverlayImageUri
Accepts an http:// url to an image you would like to use as an overlay watermark
over the encoded video. The image can be a png image, and png transparency is supported.
Optional
OverlayOffsetX
Allows customization of the position of an image watermark. Accepts an integer value
representing the desired horizonal pixel offset from the 'OverlayOffsetFrom' location
Optional
e.g. if OverlayOffsetX = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap to the left of the bottom right corner.
e.g. if OverlayOffsetX = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap to the left of the bottom right corner.
OverlayOffsetY
Allows customization of the position of an image watermark. Accepts an integer value
representing the desired vertical pixel offset from the 'OverlayOffsetFrom' location
Optional
e.g. if OverlayOffsetY = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap above the bottom right corner.
e.g. if OverlayOffsetY = 10 and OverlayOffsetFrom=BottomRight, the overlay image will be rendered with a 10 pixels gap above the bottom right corner.
NewFilename
Allows customization of the base output filename.Optional
Gomi will still append the standard file extension to the value provided here for the specified output media container.
You can also include a few predefined variables:
"[OutputMediaAssetID]" - will be replaced with the Gomi's output media asset ID. e.g "[OutputMediaAssetID]-mynewfilename" will become 42345254-mynewfilename
"[SourceMediaFilename]" - will be replaced with the source filename of the input media.
Gomi by default uses a naming convention of "[OutputMediaAssetID]-[SourceMediaFilename]". The OutputMediaAssetID helps to ensure unique filenames when files are delivered to your server.
Gomi will still append the standard file extension to the value provided here for the specified output media container.
You can also include a few predefined variables:
"[OutputMediaAssetID]" - will be replaced with the Gomi's output media asset ID. e.g "[OutputMediaAssetID]-mynewfilename" will become 42345254-mynewfilename
"[SourceMediaFilename]" - will be replaced with the source filename of the input media.
Gomi by default uses a naming convention of "[OutputMediaAssetID]-[SourceMediaFilename]". The OutputMediaAssetID helps to ensure unique filenames when files are delivered to your server.
ForcedKeyFrameInterval
Allows customization of the KeyFrame intervals when encoding to h.264. Accepts a
positive integer value.
By setting this value you force the encoder to place a keyframe at the specfied frame interval. e.g. specifying 60 forces a keyframe every 60 frames.
You should set this when targetting certain adaptive streaming protocols such as Apple HLS, Microsoft Smooth Streaming & Adobe Dynamic Streaming.
Setting ForcedKeyFrameInterval still allows other key frames to be inserted by the encoder such as at scene changes. This behaviour can be modified by the "FixedKeyFrameInterval" parameter.
By setting this value you force the encoder to place a keyframe at the specfied frame interval. e.g. specifying 60 forces a keyframe every 60 frames.
You should set this when targetting certain adaptive streaming protocols such as Apple HLS, Microsoft Smooth Streaming & Adobe Dynamic Streaming.
Setting ForcedKeyFrameInterval still allows other key frames to be inserted by the encoder such as at scene changes. This behaviour can be modified by the "FixedKeyFrameInterval" parameter.
FixedKeyFrameInterval
For h.264 encoding only. Accepts a true/false value.
Defaults to false. When set to true, does not allow the encoder to insert extra key frames except those specified by the FixedKeyFrameInterval parameter
This is often desirable when targeting the adaptive streaming protocols.
Defaults to false. When set to true, does not allow the encoder to insert extra key frames except those specified by the FixedKeyFrameInterval parameter
This is often desirable when targeting the adaptive streaming protocols.
Response Body JSON XML
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: length
{
"InputMediaID":"String",
"OutputJobs":[
{
"JobID":0,
"CustomerReferenceID":"String",
"Success":true,
"ErrorCode":String,
"Message":String,
"JobStatusLocation":"job/0"
}
],
"Success":false,
"ErrorCode":"String",
"Message":"String"
}
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: length
<CreateJobFromInputMediaResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/TranscodeEngine.API.v1.Models">
<InputMediaID>String</InputMediaID>
<OutputJobs>
<JobCreationStatus>
<CustomerReferenceID>String</CustomerReferenceID>
<JobID>0</JobID>
<JobStatusLocation>job/0</JobStatusLocation>
<Success>true</Success>
<ErrorCode>String</ErrorCode>
<ErrorMessage>String</ErrorMessage>
</JobCreationStatus>
</OutputJobs>
<Success>false</Success>
<ErrorCode>String</ErrorCode>
<Message>String</Message>
</CreateJobResponse>
Note: Look at the 'Success' value in the response to determine if the request was successful. If not, details will be provided in the ErrorCode and Message fields.