Run on Trigger | Documentation

Instill VDP allows you to run your pipelines either in the Pipeline Editor page, in the Pipeline Overview page, or via an API Endpoint.

#Run via API

Running a pipeline via an API Endpoint in Instill VDP is straightforward. You can find the cURL snippet in Pipeline Editor > Toolkit > Trigger Snippet tab.

#Run Pipeline

Navigate to the Pipeline Editor > Toolkit > Trigger Snippet tab.
Verify that your INSTILL_API_TOKEN is valid with the necessary permissions. For token management, see API Token Management.
Set up the API request with the correct API Endpoint, NAMESPACE_ID, PIPELINE_ID, and payload fields.
Send the request using the provided cURL command. Verify the response to confirm success.

LIMITATION

The maximum upload size is 32MB per request. Base64 encoding for binary files further reduces this to approximately 24MB.

#Example API Request

For pipeline setup guidance, see Create Pipeline. Here's an example request for a pipeline with input prompt and output answer:

cURL

Python

export INSTILL_API_TOKEN=********
curl -X POST 'https://api.instill.tech/v1beta/namespace/NAMESPACE_ID/pipelines/PIPELINE_ID/trigger' \
  --header "Content-Type: application/json" \
  --header "Authorization: $INSTILL_API_TOKEN" \
  --data '{
    "data": [
      {
        "variable": {
          "prompt": "hello world"
        }
      }
    ]
  }'

#Corresponding Response

{
  "outputs": [
    {
      "answer": "Hello user"
    }
  ]
}

#Sync and Async Modes

Instill VDP supports both HTTP and gRPC protocols in SYNC and ASYNC modes. The API for each mode is:

Sync Mode: Synchronous processing with immediate result return. API: /v1beta/namespace/NAMESPACE_ID/pipelines/PIPELINE_ID/trigger
Async Mode: Asynchronous processing, returning only an acknowledgment. API: /v1beta/namespace/NAMESPACE_ID/pipelines/PIPELINE_ID/trigger-async

Please refer to the API Reference for more details.

#Run Pipeline Release

Users can also trigger specific pipeline releases via the same request format, but with the release version in the endpoint:

/v1beta/namespace/NAMESPACE_ID/pipelines/PIPELINE_ID/releases/VERSION/trigger
/v1beta/namespace/NAMESPACE_ID/pipelines/PIPELINE_ID/releases/VERSION/trigger-async

Please refer to the API Reference for more details.

#Binary Files

In the above section, all requests are sent in application/json format, requiring binary data to be encoded as a base64 string. However, Instill VDP offers an alternative approach for easier handling of binary data by allowing users to trigger the pipeline via multipart/form-data.

cURL

export INSTILL_API_TOKEN=********
curl -X POST 'https://api.instill.tech/v1beta/namespace/NAMESPACE_ID/pipelines/PIPELINE_ID/trigger' \
  --header "Content-Type: multipart/form-data" \
  --header "Authorization: $INSTILL_API_TOKEN" \
  --form 'variables[0].prompt="hello world"' \
  --form 'variables[0].image=@"PATH-TO-BINARY-FILE"'

#Response Streaming

Please refer to the Streaming for more details.

#Run in the Pipeline Overview

To run a pipeline from the Pipeline Overview page:

Select a pipeline card from the Pipelines page.
Provide the necessary data or upload files.
Click the Run button to execute the pipeline and receive the results.

#Run in the Pipeline Editor

To run your pipeline in the Pipeline Editor:

Provide the necessary data or upload files.
Click the Run button to execute the pipeline and receive the streaming results.