POST Video

Overview

---

The following table contains important information about the POST method in regards to the encode process.

POST Method
Method	POST
URL or Endpoint	/api/projects/projectId/encodes
Headers	Authorization
Parameters	projectId
Body	downloadUrl, callBackUrl, enableDuplicateCheck, title, author, previewRequested, previewSeconds

The description of the URL parameter is as follows:

projectId Parameter
URL Parameter Name	projectId
Mandatory	Yes
Type	string
Description	Unique Id of the project.

Request Body

{
  "downloadUrl": "downloadUrl",
  "callBackUrl": "callBackUrl",
  "enableDuplicateCheck": true,
  "title": "string",
  "author": "string",
  "uploadFileDetailsId": 0,
  "previewRequested": false,
  "previewSeconds": 0,
  "priority": 0
}

The description of the parameters is as follows:

Body Parameter Name	Mandatory	Type	Description
downloadUrl	Yes	string	The source of the video. For a file uploaded through the Upload API send the upload's requestKey (recommended) or the upload URL returned by the Upload API. Any other public URL is accepted unless the project setting encodeUploadedFilesOnly is on, in which case only a request key or a VP upload URL is accepted, see Uploaded files only.
callBackUrl	Yes	string	URL that will be called when encoding is finished.
enableDuplicateCheck	No	boolean	Determines whether duplicate videos should be disallowed.
title	No	string	Title of the video.
author	No	string	Author of the video. When the request references an upload and the project setting enforceUploadOwnership is on, it must match the author stored on that upload, see Upload ownership.
uploadFileDetailsId	No	integer($int32)	The ID of upload file details, as returned by the Upload API. Still accepted; sending the upload's requestKey in downloadUrl is recommended instead. When both are sent they must point at the same upload.
previewRequested	No	boolean	Determines whether preview video should be generated.
previewSeconds	No	integer($int32)	Duration of the preview in seconds. Required and must be greater than zero when previewRequested is true.
priority	No	integer or null	Encoding priority of the video. 0 for Normal and 1 for High. When omitted or null, the video is encoded with normal priority. See Encoding Priority below.

info

If the enableDuplicateCheck field is set to true, the system will check for existing videos with the same content and prevent them from being encoded again. If set to false or omitted, duplicates will be allowed.

Important: This field should be enabled for both the initial video encode and any subsequent encodes. If not enabled initially, the system will not perform the duplicate check, and duplicates will be allowed, even if the content is the same. Author-scoped duplicate check: when the project setting enforceUploadOwnership is on, the check only matches a video that was created with the same author (trimmed, case-insensitive). A request without an author only matches videos created without an author. With the setting off, the check matches any video of the project with the same source, as before.

info

The downloadURL used can be one of the following:

• A request key obtained from the upload process (recommended), or the upload URL returned by the Upload API.
  For more details, see the Presigned URL to Upload File documentation.

• Any public URL pointing to the video file, as supported in previous implementations, unless the project setting encodeUploadedFilesOnly is on.

This allows flexibility when specifying the video source during upload.

Upload ownership

A request references an upload when downloadUrl is the upload's requestKey or the upload URL returned by the Upload API, or when uploadFileDetailsId is sent. Only uploads of the project in the URL are found.

When the project setting enforceUploadOwnership is on (see PATCH Project Settings):

• The author of the request must match the author stored on the referenced upload. The comparison ignores leading and trailing spaces and letter case.
• A request without author that references an upload with an author is a mismatch.
• An upload without an author is not checked.
• A mismatch, an unknown uploadFileDetailsId, an unknown request key, and a downloadUrl and uploadFileDetailsId that point at different uploads all return the same response, so the response cannot be used to find out whether an upload exists:

{
  "success": false,
  "errors": ["UPLOAD_AUTHOR_MISMATCH"],
  "messages": [],
  "result": null,
  "resultInfo": "The referenced upload does not belong to this author.",
  "errorCode": "UPLOAD_AUTHOR_MISMATCH",
  "statusCode": 403
}

When the setting is off, the author is not checked. An unknown reference or a conflicting pair of references returns 400 Bad Request with a descriptive message.

note

The author on the request is compared with the author of the upload, not with the author of the video. Changing the author of a video afterwards does not change who may encode from its upload.

Uploaded files only

When the project setting encodeUploadedFilesOnly is on, the request must reference one of the project's uploads as described above. A downloadUrl that is neither a request key nor a VP upload URL is rejected before anything is fetched:

{
  "success": false,
  "errors": ["UPLOAD_REFERENCE_REQUIRED"],
  "messages": [],
  "result": null,
  "resultInfo": "This project only accepts files uploaded through the VP upload API.",
  "errorCode": "UPLOAD_REFERENCE_REQUIRED",
  "statusCode": 400
}

A request key or upload URL that does not resolve to one of this project's uploads (for example another project's upload, or a key that does not exist) passes this check and is rejected as an unknown reference instead: 400 Bad Request with a descriptive message, or 403 UPLOAD_AUTHOR_MISMATCH when enforceUploadOwnership is also on. See Upload ownership.

Response

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "name": "name",
    "originalFile":"{originalFile}",
  },
  "resultInfo": null,
  "statusCode": 200
}

Information about the fields that appear when you receive the response are displayed in the table below.

Field Name	Type	Description
success	bool	If the response is successful it will return true. Otherwise will return false.
errors	array[string]	Indicates if there was an error.
messages	array[string]	Returns the response message from back-end.
result	array[Object]	Returns the response object.
name	string	Returns the unique name of the encoded video.
originalFile	string	Returns the original file of the video.
resultInfo	string	Returns extra information about the result.
statusCode	integer($int32)	Returns the HTTP Status Code.

If the action is successful, the service sends back an HTTP 200 or 201 response.

Errors

For information about the errors that are common to all actions, see Common Errors:

• HTTP Status Code 400: Bad Request

  Includes the fixed code UPLOAD_REFERENCE_REQUIRED when the project only accepts uploaded files, see Uploaded files only.

• HTTP Status Code 401: Unauthorized

• HTTP Status Code 403: Forbidden

  Includes the fixed code UPLOAD_AUTHOR_MISMATCH when the project enforces upload ownership, see Upload ownership.

• HTTP Status Code 404: Result Not Found

• HTTP Status Code 500: Internal Server Error

• HTTP Status Code 503: Backend Fetch Failed

Encoding Priority

The optional priority field controls how soon the video is picked up by the encoding fleet. High priority videos are placed ahead of normal ones in the encoding queue, and their playable quality is produced first, so playback becomes available sooner.

Value	Name	Behavior
0	Normal	Default. The video is encoded in the standard queue order.
1	High	The video is encoded ahead of normal priority videos.

High priority must be enabled for your project before it takes effect. If your project does not have it enabled, the request still succeeds and the video is encoded with normal priority — the response messages array explains that the requested priority was not applied:

{
  "success": true,
  "errors": [],
  "messages": [
    "High priority encoding is not enabled for this project. The video will be encoded with normal priority."
  ],
  "result": {
    "name": "{name}",
    "originalFile": "{originalFile}"
  },
  "resultInfo": null,
  "statusCode": 200
}

A priority value other than 0 or 1 is rejected with an HTTP 400 Bad Request.

info

To have high priority encoding enabled for your project, contact GjirafaTech support.

tip

The available priority values can also be retrieved from the Encoding Priorities endpoint.

On-the-Fly packager (OTFP) Functionality

As part of the video uploading process, OTFP provides temporary playback for videos immediately after uploading begins. This feature is subject to the following key considerations:

• Upon upload, you can retrieve a playbackUrl from the assets endpoint path for instant video access. This playbackUrl can also be received through the video encode submit event stream URL property.
• The playbackUrl is only valid for 24 hours after uploading completes and should not be stored for long-term use.
• A callback is triggered to your callBackUrl once encoding finishes, providing permanent video details.
• The OTFP functionality is disabled 24 hours after encoding is completed, preventing further access to the video through previously generated links.

info

We provide immediate playback of a video during its encoding process. If an encoded video becomes unplayable with an error such as status 573, it may indicate that the OTFP (On-the-Fly Packaging) period has expired. For more information, refer to the OTFP Feature Details.