POST /pipelines

Description

Create a new pipeline with specified configurations for input and output storage.

Authentication

• Required: Yes
• Method: Bearer token

Request Headers

• Authorization: Bearer [token]
• Content-Type: application/json

Parameters

Query Parameters

• format: string (Optional)
  Values: json, xml
  Overrides the Request Accept header.
• human: boolean (Optional)
  Values: true, false
  Causes the response to be in a structured, more human-readable form.
• show_null: boolean (Optional)
  Values: true, false
  If set to "true", the response will contain keys that are not set to a value.
• expand_all: boolean (Optional)
  Values: true, false
  Recursively look up referenced objects and embed the respective JSON as nested objects directly into the response.

Body Parameters

• pipeline: object (Required)
  • name: string (Required)
    Name of the new pipeline. Should be unique but not enforced.
  • description: string (Required)
    Human-readable description of the pipeline.
  • cancel_timeout: int (Optional)
    Upper limit in seconds for how long a job can remain in the "QUEUED" state before being auto-cancelled. Default is 0 (no timeout).
  • default_object_timeout: int (Optional)
    Time in seconds after which objects are considered expired.
  • input_download_dir: string (Optional)
    Base URI of an external location from where to download input videos. Supports S3, SFTP, and HTTPS.
    Format:
    • s3://access_key:secret_key@your_s3_region/bucketname/
    • sftp://login:password@host:port/path
    • https://login:password@host:port/
      For SFTP, if the path starts with ~/, it is interpreted as relative to the login user's home directory on the SFTP server; otherwise, it is treated as an absolute path. If input_download_dir is not set, input files are assumed to be already on the internal store (e.g., pre-uploaded via the Uploads API), and filenames/paths specified in job submissions are resolved relative to input_download_dir if it is set.
  • image_download_dir: string (Optional)
    Location to obtain images like logos for embedding into videos. If not set, images are assumed to be located in the regular input download dir.
  • download_options: object (Optional)
    • auto_convert_input: string (Optional)
      Whether to automatically poll&convert new input files found in input_download_dir. Set to "on" to enable auto-convert, "off" to disable. Default: "off".
    • https_certificate_check: boolean (Optional)
      Whether to verify SSL certificate of remote server before downloading files. Default: true. Set to false to allow jobs to download from HTTPS locations with self-signed/invalid certificates (otherwise such downloads will fail).
  • output_upload_dir: string (Optional)
    Remote location for uploading converted output videos. Supports S3 and SFTP. If not set, output files remain on the internal store.
  • image_upload_dir: string (Optional)
    Remote location for uploading generated thumbnails. If not set, thumbnails are stored where the regular output goes.
  • upload_options: object (Optional)
    • s3_allow_read: string (Optional)
      ACL for uploaded objects. Can be "off", "everyone" or a specific Amazon Canonical UserID. Default: "off". Note: Currently, only "off" is implemented.
    • s3_reduced_redundancy: boolean (Optional)
      Enable reduced redundancy storage on S3. Default: false. Note: Currently, only false is supported.
  • store_options: object (Optional)
    • mode: string (Optional)
      Storage mode for the internal store. Note: This option is currently not implemented at all and reserved for future use.
  • ping_urls: object (Optional)
    • error: string (Optional)
      URL to ping on error.
    • warning: string (Optional)
      URL to ping on warning.
    • started: string (Optional)
      URL to ping when a task starts.
    • finished: string (Optional)
      URL to ping when a task finishes.
  • enable_backtrace_pings: boolean (Optional)
    Set to true if you want to receive ping callbacks also for backtraces. Default: false (pings only for jobs).

Ping Callback Semantics

If ping URLs are configured, our system will call them via HTTP POST at the configured stage(s) of a job (or backtrace). The ping request always contains the full job (or backtrace) JSON as the request body and carries the following query parameters:

• event_type: The event that triggered the ping — started, finished, error or warning.
• timestamp: UNIX epoch timestamp (seconds) when the event occurred.
• payload_type: The type of the payload — job or backtrace.

Ping callbacks are authenticated with an HMAC-SHA1 signature: the request URL (path + query string) is signed with the client_secret of the pipeline's application (appended as the signature parameter) and the raw request body is additionally signed as payload_hmac (HMAC-SHA1 over the body, hex-encoded). This is the one remaining place where HMAC-SHA1 is used — everywhere else, signatures use HMAC-SHA256.

Example Request

curl -X POST "https://api.xvid.com/v1/pipelines/?human=true&show_null=true" \
  -H "Authorization: Bearer AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "name": "My own test Pipeline",
      "description": "My test Pipeline with input from S3 and output to my company sftp account",
      "cancel_timeout": 60,
      "default_object_timeout": 3600,
      "input_download_dir": "s3://AWSKEY:AWSSECRET@s3.amazonaws.com/my_bucket/",
      "image_download_dir": "https://username:password@mycompanyserver.com/my_logos/",
      "download_options": {
        "https_certificate_check": false
      },
      "output_upload_dir": "s3://AWSKEY:AWSSECRET@s3.amazonaws.com/my_bucket/",
      "image_upload_dir": "sftp://username:password@mycompanyserver.com/my_folder/",
      "upload_options": {
        "s3_allow_read": "off",
        "s3_reduced_redundancy": false
      },
      "ping_urls": {
        "error": "https://mycompany.com/ping/on_error",
        "warning": "https://mycompany.com/ping/on_warning",
        "started": "https://mycompany.com/ping/start_job",
        "finished": "https://mycompany.com/ping/finish_job"
      }
    }
  }'

Example Response

Success (201 Created)

{
  "pipeline": {
    "id": "pipeline_id",
    "name": "My own test Pipeline",
    "description": "My test Pipeline with input from S3 and output to my company sftp account",
    ...
  }
}

Error Responses

400 Bad Request

{
  "error": {
    "error_code": "0x0170001",
    "error_message": "Invalid Input"
  }
}

403 Unauthorized

{
  "error": {
    "error_code": "0x0000003",
    "error_message": "Invalid access token"
  }
}

500 Internal Server Error

{
  "error": {
    "error_code": "0x0000001",
    "error_message": "Internal server error"
  }
}

Notes

• Ensure all required fields are provided.
• Additional validation rules and potential error messages need to be documented.