Access an application in Alibaba Cloud Model Studio by using API - Alibaba Cloud Model Studio

This topic describes how to access an application that is created in Alibaba Cloud Model Studio by using API.

API reference

Feature description

You can send HTTP requests to access an application. The HTTP and HTTP Server-Sent Events (SSE) protocols are supported. You can send requests over one of the protocols based on your business requirements.

Prerequisites

Alibaba Cloud Model Studio is activated. For more information, see Activate Alibaba Cloud Model Studio.

An API key is obtained. For more information, see Obtain an API key.
An application is created and the ID of the application is obtained. For more information, see Application building and Obtain the ID and workspace of an application.

Request syntax

POST https://dashscope-intl.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion

Request parameters

Component	Parameter	Type	Description	Example
Header	Content-Type	String	The request type. Set the value to application/json.	application/json
	Accept	String	Optional. Specifies whether to enable SSE. If you set this parameter to text/event-stream, SSE is enabled. By default, this parameter is left empty.	text/event-stream
	Authorization	String	The API key.	Bearer d1**2a
	X-DashScope-SSE	String	Optional. Specifies whether to enable SSE. You can set either this parameter or the Accept parameter to enable SSE.	enable
	X-DashScope-WorkSpace	String	Optional. The ID of the workspace to which the application belongs. This parameter is required only if you want to access an application that belongs to a non-default workspace. If you access an application in the default workspace, you do not need to specify this parameter.	ws_ik******RVYCKzt
Body	input.prompt	String	The prompt to be executed. The prompt can be in Chinese or English.	the nearest park
	input.session_id	String	Optional. The unique ID of the conversation session. If you specify this parameter, the conversation is stored on the cloud and can be automatically retrieved when the model is called.
	parameters.has_thoughts	Bool	Optional. Specifies whether to return the information about document retrieval and model inference. If you set this parameter to True, the information about document retrieval and model inference is returned.
	parameters.incremental_output	Bool	Optional. Specifies whether to enable incremental output in streaming output mode. If you set this parameter to True, incremental output is enabled and the subsequent output content does not contain the historical output content. If you set this parameter to False, incremental output is disabled and the subsequent output content contains the historical output content. Default value: False.

Response parameters

Parameter	Type	Description	Example
status_code	int	The returned status code. The status code 200 indicates that the request was successful. Other status codes indicate that the request failed. If the request failed, you can obtain the error code and error message from the code and message parameters. Note This parameter is available only if you call the operation by using Python. If a request failed when you call the operation by using Java, an exception is thrown. You can obtain the exception code and message from the code and message parameters.	200
request_Id	string	The request ID.	33dcf25a-******-8b711f15614e
code	string	The error code that is returned if the request failed. If the request was successful, this parameter is not returned.
message	string	The error message that is returned if the request failed. If the request was successful, this parameter is not returned.
output.text	string	The response that is generated by the model.
output.finish_reason	string	The reason why the model stops generating content. Valid values: null: The model is generating the response. stop: The model stops generating the response due to a stop token.
output.session_id	string	The unique ID of the conversation session.	The ID maintains the context during multiple rounds of conversation.
output.thoughts[].thought	string	The thoughts of the model.
output.thoughts[].action_type	string	The type of the action that is executed by the model. Valid values: api: executes an API plug-in. response: returns the final response.
output.thoughts[].action_name	string	The name of the action that is executed by the model, such as document retrieval or API plug-in execution.
output.thoughts[].action	string	The action that is executed by the model.
output.thoughts[].action_input_stream	string	The streaming result of the input parameters.
output.thoughts[].action_input	string	The request parameters of the plug-in.
output.thoughts[].response	string	The response that is returned by the model.
output.thoughts[].observation	string	The result of document retrieval or plug-in execution.
usage	dict	The metering information, which indicates the usage metrics for the request.
usage.models[].model_id	string	The model that is called.
usage.models[].input_tokens	int	The number of tokens that are converted from the input text.
usage.models[].output_tokens	int	The number of tokens that are converted from the response generated by the model.
output.doc_reference	list	The reference information that was retrieved.
output.doc_reference[].index_id	string	The index of the reference information, which is associated with the subscript index in the <ref>[x]</ref> format in the response generated by the model.
output.doc_reference[].title	string	The title of the referenced text.
output.doc_reference[].doc_id	string	The ID of the referenced document.
output.doc_reference[].doc_name	string	The name of the referenced document.
output.doc_reference[].text	string	The text that is referenced.
output.doc_reference[].images	list	The URLs of the referenced images.

Sample request with SSE disabled

The following sample script shows how to run the cURL command to access an application when SSE is disabled.

Note

Replace YOUR_API_KEY with your API key and YOUR_APP_ID with your application ID.

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "How to cook Pork Trotters Stewed with Potatoes?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

Sample response with SSE disabled

{
  "output": {
    "finish_reason": "stop",
    "session_id": "a08c1b4e******0c4513db9eea4",
    "text": "Pork Trotters Stewed with Potatoes is a delicious and nutritious home-cooked dish, and here is an easy way to cook it:\n\n**Required materials**\n1. Trotters of 500g\n2. 2 or 3 potatoes\n3. 3 or 4 pieces of ginger\n4. 1 shallot\n5. 2 star anises\n6. A small piece of cinnamon\n7. 2 bay leaves\n8. Proper amount of cooking wine\n9. Proper amount of light soy sauce and dark soy sauce\n10. Proper amount of rock candy\n11. Proper amount of clean water\n12. Proper amount of salt\n\n**Steps**\n1. **Process trotters**: Chop the trotters into small pieces, blanch them, remove the blood and impurities, rinse them with clean water, and set them aside. \n   \n2. **Caramelize the pieces of trotters**: Add a small amount of oil to the pot, put in rock sugar and slowly boil until red and frothy, pour the blanched trotters blocks into the pot and fry, so that the surface of the trotters is evenly coated with sugar. \n\n3. **Stir-fry materials**: Add pieces of ginger, shallot, star anises, cinnamon, and bay leaves to the pot and stir-fry the materials. Next, pour cooking wine, light soy sauce, and dark soy sauce, and then add sufficient hot water to fully submerge the pork trotters. \n\n4. **Stew pork trotters**: Boil the water over high heat and skim off foams that rise to the water surface. Simmer the pork trotters for approximately 40 minutes until the pork trotters become tender and fall-off-the-bone. \n\n5. **Add potatoes**: When the pork trotters are about 70% to 80% cooked, peel and chop the potatoes into chunks, and add them to the pot. Continue to simmer for another 20 minutes or until the potatoes are thoroughly cooked and can be easily pierced with a fork. \n\n6. **Add condiments**: Add condiments such as salt based on your flavor and simmer for a few minutes to blend the flavors. \n\n7. **Finish**: Simmer until the sauce thickens and the potatoes and pork trotters are cooked through. Add chopped spring onions or cilantro and turn off the fire. \n\nThis is the method to cook Pork Trotters Stewed with Potatoes. The amount of time that is used to simmer may vary based on the tenderness and flavor that you prefer. You can determine the amount of time for simmering based on the actual case."
  },
  "usage": {
    "models": [
      {
        "output_tokens": 456,
        "model_id": "qwen-max",
        "input_tokens": 64
      }
    ]
  },
  "request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}

Sample request with SSE enabled

The following sample script shows how to run the cURL command to access an application when SSE is enabled.

Note

To ensure that the script runs as expected, replace YOUR_API_KEY with your API key and YOUR_APP_ID with your application ID.

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-SSE: enable' \
--data '{
    "input": {
        "prompt": "How to cook Pork Trotters Stewed with Potatoes?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

Sample response with SSE enabled

id:1
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"Pork Trotters"},"usage":{"models":[{"input_tokens":64,"output_tokens":1,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}

id:2
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"Pork Trotters Stewed with"},"usage":{"models":[{"input_tokens":64,"output_tokens":2,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}

id:3
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"Pork Trotters Stewed with Potatoes"},"usage":{"models":[{"input_tokens":64,"output_tokens":3,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}

... ... ... ...
... ... ... ...

id:7
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"Pork Trotters Stewed with Potatoes is a delicious and nutritious home-cooked dish, and here is an easy way to cook it\n\n**Required materials:**\n1. Trotters"},"usage":{"models":[{"input_tokens":64,"output_tokens":32,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}

Sample request for sub-workspace

The following sample script shows how to run the cURL command to access an application in a specific sub-workspace.

Note

Replace YOUR_API_KEY with your API key, YOUR_APP_ID with your application ID, and YOUR_WORKSPACE with the workspace ID of the application.

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-WorkSpace: {YOUR_WORKSPACE}' \
--data '{
    "input": {
        "prompt": "How to cook Pork Trotters Stewed with Potatoes?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

Sample response for sub-workspace

{
  "output": {
    "finish_reason": "stop",
    "session_id": "a08c1b4e******0c4513db9eea4",
    "text": "Pork Trotters Stewed with Potatoes is a delicious and nutritious home-cooked dish, and here is an easy way to cook it:\n\n**Required materials**\n1. Trotters of 500g\n2. 2 or 3 potatoes\n3. 3 or 4 pieces of ginger\n4. 1 shallot\n5. 2 star anises\n6. A small piece of cinnamon\n7. 2 bay leaves\n8. Proper amount of cooking wine\n9. Proper amount of light soy sauce and dark soy sauce\n10. Proper amount of rock candy\n11. Proper amount of clean water\n12. Proper amount of salt\n\n**Steps**\n1. **Process trotters**: Chop the trotters into small pieces, blanch them, remove the blood and impurities, rinse them with clean water, and set them aside. \n   \n2. **Caramelize the pieces of trotters**: Add a small amount of oil to the pot, put in rock sugar and slowly boil until red and frothy, pour the blanched trotters blocks into the pot and fry, so that the surface of the trotters is evenly coated with sugar. \n\n3. **Stir-fry materials**: Add pieces of ginger, shallot, star anises, cinnamon, and bay leaves to the pot and stir-fry the materials. Next, pour cooking wine, light soy sauce, and dark soy sauce, and then add sufficient hot water to fully submerge the pork trotters. \n\n4. **Stew pork trotters**: Boil the water over high heat and skim off foams that rise to the water surface. Simmer the pork trotters for approximately 40 minutes until the pork trotters become tender and fall-off-the-bone. \n\n5. **Add potatoes**: When the pork trotters are about 70% to 80% cooked, peel and chop the potatoes into chunks, and add them to the pot. Continue to simmer for another 20 minutes or until the potatoes are thoroughly cooked and can be easily pierced with a fork. \n\n6. **Add condiments**: Add condiments such as salt based on your flavor and simmer for a few minutes to blend the flavors. \n\n7. **Finish**: Simmer until the sauce thickens and the potatoes and pork trotters are cooked through. Add chopped spring onions or cilantro and turn off the fire. \n\nThis is the method to cook Pork Trotters Stewed with Potatoes. The amount of time that is used to simmer may vary based on the tenderness and flavor that you prefer. You can determine the amount of time for simmering based on the actual case."
  },
  "usage": {
    "models": [
      {
        "output_tokens": 456,
        "model_id": "qwen-max",
        "input_tokens": 64
      }
    ]
  },
  "request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}

Sample request with references

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-WorkSpace: {YOUR_WORKSPACE}' \
--data '{
    "input": {
        "prompt": "How to create an API key, obtain an API key, and check the permissions of an API key in Alibaba Cloud Model Studio?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

Sample response with references

{
  "output": {
    "finish_reason": "stop",
    "session_id": "a08c1b4e******0c4513db9eea4",
    "doc_references": [
      {
        "doc_id": "doc_656587d5a56446788ffddd041d88009310105",
        "doc_name": "Obtain an API key",
        "index_id": "1",
        "text": "Create an API key and check the permissions of the API key \nCreate an API key\nLog on to Alibaba Cloud Model Studio. In the upper-right corner of the homepage, move the pointer over the profile picture and select API-KEY to go to the API Key Management page. Alibaba Cloud Model Studio Documentation Go to Trial Center Workspace Management Default Workspace v Day API KEY 6Notice on service interruption of Plug-in Center of Alibaba Cloud Model Studio, Plug-in Center Notice 7Homepage Privacy Policy Test Protocol Popular Model More Popular Application Template Model Center-DashScope Log Out Model Service Tongyi Qianwen-Plus Tongyi Qianwen-Turbo Tongyi Qianwen-Open Source-7B RAG Enhanced Application Template My Model Tongyi Qianwen-Plus supports multiple languages such as Chinese and English Tongyi Qianwen-Turbo supports multiple languages such as Chinese and English Parameters of Tongyi Qianwen-Open Source-7B are aligned by running commands Based on Tongyi Qianwen, the knowledge retrieval-based LLM is enhanced. Model Plaza Input.  The model supports up to 8k tokens of context, with the API restricting user input to 6k. The model supports document retrieval for text generation based on the structured /unstructured content 7",
        "title": "Obtain an API key|Create an API key",
        "images": ["http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/publicDocStructure/docmind-84e699ecfb4f4cb4befe6ddec8aff914/5.png?&x-oss-process=image%2Fcrop%2Cx_224%2Cy_176%2Cw_901%2Ch_638", "http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/publicDocStructure/docmind-84e699ecfb4f4cb4befe6ddec8aff914/5.png?&x-oss-process=image%2Fcrop%2Cx_211%2Cy_916%2Cw_926%2Ch_578"]
      },
      {
        "doc_id": "doc_656587d5a56446788ffddd041d88009310105",
        "doc_name": "Obtain an API key",
        "index_id": "2",
        "text": "Take note of the permissions of an API key when you access Alibaba Cloud Model Studio by calling API operations or using SDKs. 1. You can use the API key of an Alibaba Cloud account to access the resources and models that can be accessed by the account in all workspaces. 2. You can use the API key of a RAM user to access the resources that can be accessed by the RAM user in the workspaces. 3. You cannot use the API key of a RAM user to access the resources in the default workspace of an Alibaba Cloud account. If you want to access the resources that can be accessed in the default workspace of an Alibaba Cloud account as a RAM user, use one of the following methods: (1) Apply for the API key of the Alibaba Cloud account for the RAM user. (2) Grant the management permissions on the default workspace to the RAM user. This way, the RAM user can view the API-KEY menu in the default workspace. The API key of the Alibaba Cloud account is displayed on the API Key Management page. You can access the default workspace as a RAM user by using the API key of the Alibaba Cloud account. Alibaba Cloud Model Studio Documentation Experience Center v0 Primary Account Space API KEY Management Center Create New API-KEY 8 Application Service ID API-KEY Creation Time Actions My Applications 46098 sk-aQbil 2024-03-02 15:29:32 View Delete Application Plaza 47982 sk-D5EIA 2024-03-06 20:04:27 View Delete Experience Center Application Tools Plugin Center Application Evaluation Enterprise Knowledge Base System Management Product System Tools Invocation Statistics Billing Management API KEY Dimension Management Permission Management User Management Role Management",
        "title": "Check the permissions of an API key",
        "images": ["http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/publicDocStructure/docmind-84e699ecfb4f4cb4befe6ddec8aff914/5.png?&x-oss-process=image%2Fcrop%2Cx_224%2Cy_176%2Cw_901%2Ch_638", "http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/publicDocStructure/docmind-84e699ecfb4f4cb4befe6ddec8aff914/5.png?&x-oss-process=image%2Fcrop%2Cx_211%2Cy_916%2Cw_926%2Ch_578"]
      },
      {
        "doc_id": "doc_656587d5a56446788ffddd041d88009310105",
        "doc_name": "Obtain an API key",
        "index_id": "4",
        "text": ",The model supports up to 8k tokens of context, with the API restricting user input to 6k. "Competence", supports text generation scenarios based on structured/non-structured content. Call Documentation 7 Call Documentation 7 Call Documentation Create Application Free Model Experience Model Experience Center Prompt Project Novice Guide Model Tools Model Optimization Direct Call Model Deployment Experience Model Invoke Model Prompt visualization, experience the Tongyi large model One-click activation, invoke large model services. Improve efficiency by using preset Prompt templates or Prompt optimization tools. Model Assessment Experience Now Call Now Immediately head to Training Data Application Center Train Model Tutorial 8 Application Services Upload Training Data Train Model Evaluate Model My Applications Immediately head to Training Data Application Center Train Model Tutorial Application Services Upload Training Data Train Model Evaluate Model My Applications Prepare and upload SFT training data Conduct model fine-tuning by using various methods Evaluate by using visual tools in full-auto/half-auto mode Application Plaza: Go Now Go Now Go Now Application Experience Center Create custom RAG application tutorial Click Create New API-KEY to automatically generate an API-KEY that belongs to this account. Alibaba Cloud Model Studio←Return to Homepage API KEY Management Create API KEY API-KEY ID API-KEY Created At Actions46098 sk-a****Qbil 2024-03-02 15:29:32 View47982 sk-D****5EIA 2024-03-06 20:04:27 View Delete",
        "title": "Create an API key",
        "images": ["http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/publicDocStructure/docmind-84e699ecfb4f4cb4befe6ddec8aff914/5.png?&x-oss-process=image%2Fcrop%2Cx_224%2Cy_176%2Cw_901%2Ch_638", "http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/publicDocStructure/docmind-84e699ecfb4f4cb4befe6ddec8aff914/5.png?&x-oss-process=image%2Fcrop%2Cx_211%2Cy_916%2Cw_926%2Ch_578"]
      }
    ],
    "text": "You can perform the following operations to create an API key. Log on to Alibaba Cloud Model Studio by using an Alibaba Cloud account<ref>[1][4]</ref>. In the upper-right corner of the homepage, move the pointer over the profile picture<ref>[1]</ref>, and click API-KEY to go to the API Key Management page. On the API Key Management page, click Create API Key<ref>[4]</ref>. \n\nAn API key is created. After you create an API key, the API key is displayed on the API Key Management page. You can view and manage the API key on the page<ref>[1][4]</ref>. \n\nThe permissions of an API key are granted based on the following rules:\n1. The API key of an Alibaba Cloud account has the permissions to access all the resources that can be accessed in all workspaces.<ref>[2]</ref>. \n2. The API key of a RAM user can access the resources that can be accessed by the RAM user in the workspaces.<ref>[2]</ref>. \n3. You cannot use the API key of a RAM user to access the resources in the default workspace of an Alibaba Cloud account. If you want to access the resources in the default workspace of an Alibaba Cloud account as a RAM user, use one of the following methods: 1. Request the Alibaba Cloud account to share its API key with the RAM user<ref>[2]</ref>. 2. Grant the RAM user the management permissions on the default workspace. This way, you can access the default workspace as a RAM user by using the API key of the Alibaba Cloud account<ref>[2]</ref>. \n\nIn conclusion, you can create or obtain an API key with ease and flexibly manage permissions of API keys by using Alibaba Cloud accounts and RAM users. This ensures the security of resources."
  },
  "usage": {
    "models": [
      {
        "model_id": "qwen-max",
        "input_tokens": 2004,
        "output_tokens": 313
      }
    ]
  },
  "request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}

If the reference display feature is enabled for the application, subscript indexes such as <ref>[x1][x2]</ref> are added to the response generated by the model. A subscript index indicates that the segment of the response is generated based on specific reference information. The reference information is stored in the output.doc_references parameter. You can use the output.doc_references[x].index_id parameter to associate the subscript indexes with the reference information.

Sample error response

If an error occurs during a request, the error code and error message are returned in the code and message parameters.

{"code":"InvalidApiKey","message":"Invalid API-key provided.","request_id":"2637fcf9-32b1-9f4e-b0e9-1724d4aea00e"}

Status codes

For more information about the status codes that are returned, see Status codes.