You may need to pass custom parameters of plug-ins and workflows or the authentication token for plug-ins. This topic describes how to pass through custom parameters when calling an application.
Prerequisites
You must first obtain an API key and set the API key as an environment variable. If you need to use SDK, you must install the SDK.
Custom plug-in parameter pass-through
This section uses the Dormitory Convention Query Tool as an example to show how to pass through custom parameters for custom plug-ins when calling applications with API.
Make sure the corresponding plug-in is added to the application and the application is published. For more information about plug-ins, see Plug-in overview.
No authentication required
Go to Plug-in Center and click Modify Plug-in on the desired plug-in card.
On the Modify Custom Plug-in page, configure the interface information. Add a pass-through identifier to the parameter. For example, to set
article_indexas the pass-through parameter, addx-source: userand click Save.
Call the plug-in with the API. Use
biz_paramsin theinputobject to pass the index number.Python
Sample request
import os from http import HTTPStatus # Recommended dashscope SDK version >= 1.14.0 from dashscope import Application import dashscope dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1' biz_params = { # Custom plug-in input parameter pass-through for agent applications, replace the custom plug-in ID with {your_plugin_code} "user_defined_params": { "{your_plugin_code}": { "article_index": 2}}} response = Application.call( # If the environment variable is not configured, you can replace the line below with your API key: api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage. api_key=os.getenv("DASHSCOPE_API_KEY"), app_id='YOUR_APP_ID', prompt='Dormitory Convention Content', biz_params=biz_params) if response.status_code != HTTPStatus.OK: print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message)) else: print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))Sample response
request_id=d97e3c58-7a75-9ea1-9ecf-d5be869b748e output={"text": "The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This reminds us to maintain good interpersonal relationships in dormitory life and create a harmonious and positive living and learning environment together. If you need to know more about the convention content, please tell me the specific ordinal number or continue to ask questions.", "finish_reason": "stop", "session_id": "8ec3fa6c59794ed3ab803b921aa38d7a", "thoughts": null, "doc_references": null} usage={"models": [{"model_id": "qwen-max", "input_tokens": 453, "output_tokens": 107}]}Java
Sample request
package org.example; import com.alibaba.dashscope.app.*; import com.alibaba.dashscope.exception.ApiException; import com.alibaba.dashscope.exception.InputRequiredException; import com.alibaba.dashscope.exception.NoApiKeyException; import com.alibaba.dashscope.utils.JsonUtils; import io.reactivex.Flowable; import com.alibaba.dashscope.utils.Constants; public class Test { static { Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1"; } public static void streamCall() throws NoApiKeyException, InputRequiredException { String bizParams = "{\"user_defined_params\":{\"{your_plugin_code}\":{\"article_index\":2}}}"; ApplicationParam param = ApplicationParam.builder() // If the environment variable is not configured, you can replace the line below with your API key: api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage. .apiKey(System.getenv("DASHSCOPE_API_KEY")) .appId("YOUR_APP_ID") .prompt("Dormitory Convention Content") .bizParams(JsonUtils.parse(bizParams)) .build(); Application application = new Application(); Flowable<ApplicationResult> result = application.streamCall(param); result.blockingForEach(data -> { System.out.printf("requestId: %s, text: %s, finishReason: %s\n", data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason()); }); } public static void main(String[] args) { try { streamCall(); } catch (ApiException | NoApiKeyException | InputRequiredException e) { System.out.printf("Exception: %s", e.getMessage()); } System.exit(0); } }Sample response
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: Dormitory, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second item of the dormitory convention, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely., finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need to know other items, please tell me the ordinal number, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need to know other items, please tell me the ordinal number., finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need to know other items, please tell me the ordinal number., finishReason: stopReplace YOUR_APP_ID with the application ID and {YOUR_PLUGIN_ID} with the custom plug-in ID.
curl
Sample request
curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "input": { "prompt": "Dormitory Convention Content", "biz_params": { "user_defined_params": { "YOUR_PLUGIN_ID": { "article_index": 2 } } } }, "parameters": {}, "debug":{} }'Sample response
{"output": {"finish_reason":"stop", "session_id":"e151267ffded4fbdb13d91439011d31e", "text":"The second content of the dormitory convention is: “Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely.” This means that in dormitory life, everyone should support each other and create a harmonious and positive living environment together."}, "usage":{"models":[{"output_tokens":94,"model_id":"qwen-max","input_tokens":453}]}, "request_id":"a39fd2b5-7e2c-983e-84a1-1039f726f18a"}%Replace YOUR_APP_ID with the application ID and YOUR_PLUGIN_ID with the custom plug-in ID.
If you pass a parameter without
x-source, the parameter is not effective. Also, you need to use natural language to describe the function of the plug-in, so that the LLM can better decide whether to use the plug-in.
Authentication required
Go to Plug-in Center and click Modify Plug-in on the desired plug-in card.
On the Modify Custom Plug-in page, enable authentication, select User-level Authentication.
Enter a Parameter Name and click Save.
Pass the user-level authentication token when making API calls.
Use
biz_paramsto pass the relevant data and useuser_tokento pass the token information. After successful authentication, the application can query specific entries based on the index number and return the results.Python
Sample request
from http import HTTPStatus import os # Recommended dashscope SDK version >= 1.14.0 from dashscope import Application import dashscope dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1' biz_params = { # Custom plug-in authentication pass-through for agent applications, replace the custom plug-in ID with {your_plugin_code} and token with YOUR_TOKEN "user_defined_params": { "{your_plugin_code}": { "article_index": 2}}, "user_defined_tokens": { "{your_plugin_code}": { "user_token": "YOUR_TOKEN"}}} response = Application.call( # If the environment variable is not configured, you can replace the line below with your API key: api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage. api_key=os.getenv("DASHSCOPE_API_KEY"), app_id='YOUR_APP_ID', prompt='Dormitory Convention Content', biz_params=biz_params) if response.status_code != HTTPStatus.OK: print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message)) else: print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))Sample response
request_id=e928fe3b-3df3-9a3f-9ea4-884aed3aea3c output={"text": "The second content of the dormitory convention is: “Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely.” This emphasizes that dormitory members should establish harmonious, supportive, and respectful relationships.", "finish_reason": "stop", "session_id": "c3b909e48a0b4867a57b482dece9cbb7", "thoughts": null, "doc_references": null} usage={"models": [{"model_id": "qwen-max", "input_tokens": 432, "output_tokens": 82}]}Java
Sample request
package org.example; import com.alibaba.dashscope.app.*; import com.alibaba.dashscope.exception.ApiException; import com.alibaba.dashscope.exception.InputRequiredException; import com.alibaba.dashscope.exception.NoApiKeyException; import com.alibaba.dashscope.utils.JsonUtils; import io.reactivex.Flowable; import com.alibaba.dashscope.utils.Constants; public class Test { static { Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1"; } public static void streamCall() throws NoApiKeyException, InputRequiredException { String bizParams = "{\"user_defined_params\":{\"{your_plugin_code}\":{\"article_index\":2}}," + "\"user_defined_tokens\":{\"{your_plugin_code}\":{\"user_token\":\"YOUR_TOKEN\"}}}"; ApplicationParam param = ApplicationParam.builder() // If the environment variable is not configured, you can replace the line below with your API key: api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage. .apiKey(System.getenv("DASHSCOPE_API_KEY")) .appId("YOUR_APP_ID") .prompt("Dormitory Convention Content") .bizParams(JsonUtils.parse(bizParams)) .build(); Application application = new Application(); Flowable<ApplicationResult> result = application.streamCall(param); result.blockingForEach(data -> { System.out.printf("requestId: %s, text: %s, finishReason: %s\n", data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason()); }); } public static void main(String[] args) { try { streamCall(); } catch (ApiException | NoApiKeyException | InputRequiredException e) { System.out.printf("Exception: %s", e.getMessage()); } System.exit(0); } }Sample response
requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: Dormitory, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second item of the dormitory convention, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely., finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need to know other items, please tell me the ordinal number, finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need to know other items, please tell me the ordinal number., finishReason: null requestId: 48bb400a-d050-9f5c-afbd-c1adb25f6a43, text: The second content of the dormitory convention is: Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely. This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life. If you need to know other items, please tell me the ordinal number., finishReason: stopReplace YOUR_APP_ID with the application ID, YOUR_PLUGIN_ID with the custom plug-in ID, and YOUR_TOKEN with the authentication token.
curl
Sample request
curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "input": { "prompt": "Dormitory Convention Content", "biz_params": { "user_defined_params": { "YOUR_PLUGIN_ID": { "article_index": 2 } }, "user_defined_tokens": { "YOUR_PLUGIN_ID": { "user_token": "YOUR_TOKEN" } } } }, "parameters": {}, "debug":{} }'Sample response
{"output":{"finish_reason":"stop", "session_id":"d3b5c3e269dc40479255a7a02df5c630", "text":"The second content of the dormitory convention is: “Dormitory members should help each other, care for each other, learn from each other, and improve together; be tolerant and modest, respect each other, and treat each other sincerely.” This emphasizes the importance of harmonious coexistence and mutual progress among members in dormitory life."}, "usage":{"models":[{"output_tokens":80,"model_id":"qwen-max","input_tokens":432}]}, "request_id":"1f77154c-edc3-9003-b622-816fa2f849cf"}%Replace YOUR_APP_ID with the application ID, YOUR_PLUGIN_ID with the custom plug-in ID, and YOUR_TOKEN with the authentication token.
For workflow applications and agent orchestration applications
This section uses City Administrative Regions Query as an example to show how to pass through custom parameters for nodes.
Go to , select or create a workflow or agent orchestration application.
Set the
cityparameter in the Start node. Add and configure an LLM node.Insert the
cityvariable in the User Prompt input box.Configure the End node and click Publish.
Use the API
Use
promptto pass thequeryparameter andbiz_paramsfor the custom parametercity. The LLM can query the city administrative regions based on the city name parameter and return the results.Python
Sample request
import os from http import HTTPStatus from dashscope import Application import dashscope dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1' # Custom input parameter pass-through for workflow and agent orchestration applications biz_params = {"city": "Singapore"} response = Application.call( # If the environment variable is not configured, you can replace the line below with your API key: api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage. api_key=os.getenv("DASHSCOPE_API_KEY"), app_id='YOUR_APP_ID', prompt='Query the administrative divisions of this city', biz_params=biz_params # Pass business parameters ) if response.status_code != HTTPStatus.OK: print(f'request_id={response.request_id}, code={response.status_code}, message={response.message}') else: print(f'output={response.output}, usage={response.usage}')Sample response
output={"text": "Singapore is a city-state and does not have traditional administrative regions like many other countries. However, it is divided into smaller areas for administrative purposes. These are known as planning regions, which include: 1. Central Region (Central Singapore) 2. North Region (North Singapore) 3. North-East Region (North-East Singapore) 4. East Region (East Singapore) 5. South Region (South Singapore) 6. West Region (West Singapore) Additionally, there are smaller districts and towns that are part of these regions. Each region and district has its own town council responsible for local administration.", "finish_reason": "stop", "session_id": "6a3bf88eacda43128f57d87e29323166", "thoughts": null, "doc_references": null}, usage={"models": null}Replace YOUR_APP_ID with the application ID.
Java
Sample request
package org.example; import com.alibaba.dashscope.app.*; import com.alibaba.dashscope.exception.ApiException; import com.alibaba.dashscope.exception.InputRequiredException; import com.alibaba.dashscope.exception.NoApiKeyException; import com.alibaba.dashscope.utils.JsonUtils; import io.reactivex.Flowable; import com.alibaba.dashscope.utils.Constants; public class Test { static { Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1"; } public static void streamCall() throws NoApiKeyException, InputRequiredException { String bizParams = "{\"city\":\"Singapore\"}"; ApplicationParam param = ApplicationParam.builder() // If the environment variable is not configured, you can replace the line below with your API key: api_key="sk-xxx". However, it is not recommended to hard code the API Key directly into the code in a production environment to reduce the risk of API Key leakage. .apiKey(System.getenv("DASHSCOPE_API_KEY")) .appId("YOUR_APP_ID") .prompt("Query the administrative divisions of this city") .bizParams(JsonUtils.parse(bizParams)) .build(); Application application = new Application(); Flowable<ApplicationResult> result = application.streamCall(param); result.blockingForEach(data -> { System.out.printf("requestId: %s, text: %s, finishReason: %s\n", data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason()); }); } public static void main(String[] args) { try { streamCall(); } catch (ApiException | NoApiKeyException | InputRequiredException e) { System.out.printf("Exception: %s", e.getMessage()); } System.exit(0); } }Sample response
requestId: 713ebb6e-8840-9f31-bd58-e7e931ef345d, text: Singapore is a city-state and does not have traditional administrative regions like many other countries. However, it is divided into smaller areas for administrative purposes. These are known as planning regions, which include: 1. Central Region (Central Singapore) 2. North Region (North Singapore) 3. North-East Region (North-East Singapore) 4. East Region (East Singapore) 5. South Region (South Singapore) 6. West Region (West Singapore) Additionally, there are smaller districts and towns that are part of these regions. Each region and district has its own town council responsible for local administration., finishReason: stopReplace YOUR_APP_ID with the application ID.
curl
Sample request
curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/apps/YOUR_APP_ID/completion \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "input": { "prompt": "Query the administrative divisions of this city", "biz_params": { "city": "Singapore"} }, "parameters": {} }'Sample response
{"output":{"finish_reason":"stop","session_id":"c211219896004b50a1f6f66f2ec5413e", "text":"Singapore is a city-state and does not have traditional administrative regions like many other countries. However, it is divided into smaller areas for administrative purposes. These are known as planning regions, which include: 1. Central Region (Central Singapore) 2. North Region (North Singapore) 3. North-East Region (North-East Singapore) 4. East Region (East Singapore) 5. South Region (South Singapore) 6. West Region (West Singapore) Additionally, there are smaller districts and towns that are part of these regions. Each region and district has its own town council responsible for local administration."},"usage":{}, "request_id":"02c3c9e1-7912-9505-91aa-248d04fb1f5d"}Replace YOUR_APP_ID with the application ID.