备案控制台
文档
产品文档
输入文档关键字查找
首页 大模型服务平台百炼 开发参考 应用中心 应用调用 API详情

API详情

更新时间：
一键部署
我的收藏

本文主要介绍如何使用API调用阿里云百炼的应用，即从应用中心->我的应用中新建的应用。

API详情

功能描述

应用调用同时支持 HTTP 调用来完成客户的响应，目前提供普通 HTTP 和 HTTP SSE 两种协议，您可根据自己的需求自行选择。

前提条件

提交接口调用

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

入参描述

传参方式

字段

类型

必选

描述

示例值

Header

Content-Type

String

是

请求类型：application/json

application/json

Accept

String

否

*/*，选择text/event-stream则会开启 SSE 响应，默认无设置

text/event-stream

Authorization

String

是

API-Key，例如：Bearer d1**2a

Bearer d1**2a

X-DashScope-SSE

String

否

跟Accept: text/event-stream 二选一即可启用SSE响应

enable

X-DashScope-WorkSpace

String

否

业务空间标识，当调用子业务空间的应用时，需要传递workspace标识，调用默认业务空间的应用无需传递workspace。

ws_ik******RVYCKzt

Body

input.prompt

String

是

用户当前输入的期望模型执行指令，支持中英文。

哪个公园距离我更近

input.session_id

String

否

对话历史会话唯一标识，传入session_id后，将在云端进行对话历史记录，调用大模型将自动携带存储的对话历史

parameters.has_thoughts

Bool

否

是否输出检索召回处理过程信息。开启后，将返回文档检索召回和模型推理的过程信息。

parameters.incremental_output

Bool

否

控制在流式输出模式下是否开启增量输出，即后续输出内容是否包含已输出的内容。设置为True时，将开启增量输出模式，后面输出不会包含已经输出的内容，您需要自行拼接整体输出；设置为False则会包含已输出的内容。

默认False。

出参描述

字段

类型

描述

示例值

status_code

int

200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。

说明

Python才有这个字段，Java失败会抛异常，异常信息为code，message内容。

200

request_Id

string

系统生成的标志本次调用的id。

33dcf25a-******-8b711f15614e

code

string

表示请求失败，显示错误码，成功则忽略。

message

string

失败，返回失败详细信息，成功则忽略。

output.text

string

模型生成回复。

output.finish_reason

string

正在生成时为null，生成结束时如果由于停止token导致则为stop。

output.session_id

string

对话历史会话的唯一标识。

在多轮会话时，可以使用此标识进行多轮会话保持。

output.thoughts[].thought

string

模型的思考结果。

output.thoughts[].action_type

string

大模型返回的执行步骤类型

api：执行API插件，response：返回最终结果。

output.thoughts[].action_name

string

执行的action名称，如文档检索、API插件。

output.thoughts[].action

string

执行的步骤。

output.thoughts[].action_input_stream

string

入参的流式结果。

output.thoughts[].action_input

string

插件的输入参数。

output.thoughts[].response

string

模型调用返回的结果。

output.thoughts[].observation

string

检索或插件的返回结果。

usage

dict

计量信息，表示本次请求的计量数据。

usage.models[].model_id

string

本次应用调用到的模型。

usage.models[].input_tokens

int

用户输入文本转换成Token后的长度。

usage.models[].output_tokens

int

模型生成回复转换为Token后的长度。

output.doc_reference

list

检索的引用信息。

output.doc_reference[].index_id

string

引用信息的索引，用以关联模型回复中的角标索引<ref>[x]</ref>

output.doc_reference[].title

string

引用的文本片段标题

output.doc_reference[].doc_id

string

引用的文档Id

output.doc_reference[].doc_name

string

引用的文档名

output.doc_reference[].text

string

引用的具体文本内容

output.doc_reference[].images

list

引用的图片URL列表

请求示例（SSE 关闭）

以下示例展示通过CURL命令来调用应用的脚本（SSE 关闭）。

说明

需要使用您的API-KEY替换示例中的YOUR_API_KEY，并将APP-ID替换示例中的YOUR_APP_ID，代码才能正常运行。

curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "prompt": "如何做土豆炖猪脚?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

响应示例（SSE关闭）

{
  "output": {
    "finish_reason": "stop",
    "session_id": "a08c1b4e******0c4513db9eea4",
    "text": "土豆炖猪脚是一道美味可口、营养丰富的家常菜，下面是一种简单的制作方法：\n\n**材料准备：**\n1. 猪脚（猪蹄）500克\n2. 土豆2-3个\n3. 生姜3-4片\n4. 大葱1根\n5. 八角2颗\n6. 桂皮一小块\n7. 香叶2片\n8. 料酒适量\n9. 生抽、老抽各适量\n10. 冰糖适量\n11. 清水适量\n12. 盐适量\n\n**步骤：**\n1. **猪脚处理**：猪脚剁成小块，放入开水中焯水，去除血水和杂质，捞出后用清水冲洗干净备用。\n   \n2. **炒糖色**：锅中加入少量油，放入冰糖小火慢慢熬化至红色且有泡沫时，将焯过水的猪脚块倒入锅中翻煎，使猪脚表面均匀地裹上糖色。\n\n3. **炖煮**：加入切好的姜片、葱段以及八角、桂皮、香叶等香料一同翻炒出香味。然后烹入料酒，加入生抽、老抽调色，再加入足够的热水没过猪脚。\n\n4. **炖煮猪脚**：大火烧沸后撇去浮沫，转中小火慢炖约40分钟至猪脚软烂。\n\n5. **加入土豆**：在猪脚炖至七八成熟时，将土豆削皮切块，加入锅中，继续炖煮约20分钟，直到土豆熟透且能轻易插入筷子。\n\n6. **调味**：最后根据个人口味加盐调味，炖煮几分钟让味道充分融合即可。\n\n7. **出锅**：炖至汤汁浓稠，土豆和猪脚都完全熟透后，撒上葱花或者香菜点缀，即可关火出锅。\n\n以上就是土豆炖猪脚的基本做法，具体炖煮时间可能因猪脚的老嫩程度和个人口感喜好有所不同，可以根据实际情况调整。"
  },
  "usage": {
    "models": [
      {
        "output_tokens": 456,
        "model_id": "qwen-max",
        "input_tokens": 64
      }
    ]
  },
  "request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}

请求示例（SSE开启）

以下示例展示通过CURL命令来调用应用的脚本（SSE 开启）。

说明

需要使用您的API-KEY替换示例中的YOUR_API_KEY，并将APP-ID替换示例中的YOUR_APP_ID，代码才能正常运行。

curl --location 'https://dashscope.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": "如何做土豆炖猪脚?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

响应示例（SSE开启）

id:1
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"土豆"},"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":"土豆炖"},"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":"土豆炖猪"},"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":"土豆炖猪脚是一道美味可口、营养丰富的家常菜，下面是一种简单的制作方法：\n\n**材料准备：**\n1. 猪"},"usage":{"models":[{"input_tokens":64,"output_tokens":32,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}

请求示例（子业务空间）

以下示例展示通过CURL命令来调用指定业务空间的应用的脚本。

说明

需要使用您的API-KEY替换示例中的YOUR_API_KEY，并将APP-ID替换示例中的YOUR_APP_ID，然后将WORKSPACE替换示例中的YOUR_WORKSPACE，代码才能正常运行。

curl --location 'https://dashscope.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": "如何做土豆炖猪脚?"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

响应示例（子业务空间）

{
  "output": {
    "finish_reason": "stop",
    "session_id": "a08c1b4e******0c4513db9eea4",
    "text": "土豆炖猪脚是一道美味可口、营养丰富的家常菜，下面是一种简单的制作方法：\n\n**材料准备：**\n1. 猪脚（猪蹄）500克\n2. 土豆2-3个\n3. 生姜3-4片\n4. 大葱1根\n5. 八角2颗\n6. 桂皮一小块\n7. 香叶2片\n8. 料酒适量\n9. 生抽、老抽各适量\n10. 冰糖适量\n11. 清水适量\n12. 盐适量\n\n**步骤：**\n1. **猪脚处理**：猪脚剁成小块，放入开水中焯水，去除血水和杂质，捞出后用清水冲洗干净备用。\n   \n2. **炒糖色**：锅中加入少量油，放入冰糖小火慢慢熬化至红色且有泡沫时，将焯过水的猪脚块倒入锅中翻煎，使猪脚表面均匀地裹上糖色。\n\n3. **炖煮**：加入切好的姜片、葱段以及八角、桂皮、香叶等香料一同翻炒出香味。然后烹入料酒，加入生抽、老抽调色，再加入足够的热水没过猪脚。\n\n4. **炖煮猪脚**：大火烧沸后撇去浮沫，转中小火慢炖约40分钟至猪脚软烂。\n\n5. **加入土豆**：在猪脚炖至七八成熟时，将土豆削皮切块，加入锅中，继续炖煮约20分钟，直到土豆熟透且能轻易插入筷子。\n\n6. **调味**：最后根据个人口味加盐调味，炖煮几分钟让味道充分融合即可。\n\n7. **出锅**：炖至汤汁浓稠，土豆和猪脚都完全熟透后，撒上葱花或者香菜点缀，即可关火出锅。\n\n以上就是土豆炖猪脚的基本做法，具体炖煮时间可能因猪脚的老嫩程度和个人口感喜好有所不同，可以根据实际情况调整。"
  },
  "usage": {
    "models": [
      {
        "output_tokens": 456,
        "model_id": "qwen-max",
        "input_tokens": 64
      }
    ]
  },
  "request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}

请求示例（展示回答来源）

curl --location 'https://dashscope.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": "百炼的API-KEY的创建步骤、获取方法和权限范围分别是什么？"
    },
    "parameters":  {},
    "debug": {}
}' --verbose

响应示例（展示回答来源）

{
  "output": {
    "finish_reason": "stop",
    "session_id": "a08c1b4e******0c4513db9eea4",
    "doc_references": [
      {
        "doc_id": "doc_656587d5a56446788ffddd041d88009310105",
        "doc_name": "获取API-KEY",
        "index_id": "1",
        "text": "API-KEY的创建、获取及权限范围。\nAPI-KEY的创建\n功能位置登录以后，右上角头像位置，鼠标悬浮后，展示API-KEY，点击后进入API-KEY管理页面。阿里云百炼大楼型服务平口产品文档 前往体验中心 只业务空间管理默认业务空间v日 API KEY6阿里云百炼插件中心停服调整公告,插件中心公告7首页 隐私政策测试协议热门模型 更多热门应用模板模型中心-灵积退出登录品模型服务通义千问-Plus 通义千问-Turbo Q通义千问-开源版-7B 巴RAG检索增强应用模板我的模型通义千间超大规模语言模型增强版,支持中文英文等不同语言 通义千问超大规模语言模型,支持中文英文等不同语言输入, 通义千问对外开源的7B规横参数量的经过人类指令对齐的chat 在通义千间模型基础之上,专项增强「基于知识检索的大模型生模型广场 输入。 模型,模型支持 8k tokens上下文,API限定用户输入为6k. 成能力」,支持基于结构化/非结构化内容的文字生成场景调用文档7",
        "title": "获取API-KEY|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": "获取API-KEY",
        "index_id": "2",
        "text": "当通过API或SDK进行百炼平台的使用时，要注意API-KEY的权限范围1、主账号创建的API-KEY，可以访问所有业务空间下已被授权过的资源（比如资源、模型等）。2、子账号创建的API-KEY，可以访问当前子账号具有权限的业务空间下已被授权过的资源。3、子账号创建的API-KEY，不可以访问主账号业务空间（又叫作默认业务空间）下的一切资源。如果子账号想要访问主账号业务空间下已被授权过的资源，有2种解决方案：（1）需要向主账号索要API-KEY来进行调用。（2）可以让主账号给子账号授权“主账号空间”管理员权限，子账号则可以在“主账号业务”空间下看到一个【API-KEY】菜单，此页面展示的是主账号的API-KEY，子账号可以用该主账号API-KEY进行访问。阿里云百炼日产品文档 前往体验中心v 0只主账号空间v日API KEY 管理用中心 创建新的API-KEY8应用服务ID API-KEY 创建时间 操作我的应用46098 sk-a****Qbil 2024-03-02 15:29:32 查看删除应用广场47982 sk-D****5EIA 2024-03-06 20:04:27 查看删除应用体验中心应用工具插件中心应用评测企业知识库系统管理品系统工具调用统计计费管理API KEY维度管理回权限管理用户管理角色管理",
        "title": "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": "获取API-KEY",
        "index_id": "4",
        "text": ",模型支持 8k tokens上下文,API限定用户输入为6k. 成能力」,支持基于结构化/非结构化内容的文字生成场景调用文档7 调用文档7 调用文档 创建应用 免费体验模型体验中心Prompt工程新手引导模型工具模型调优 直接调用 模型部署 体验模型 调用模型 prompt可视化、免费地体验通义大模型 一键开通,快速调用大模型服务 通过预置Prompt模板, 或Prompt优化工具提升效集模型评测立即体秘 立即调用 立即前往桂训练数据应用中心训练专属模型教程◎8应用服务上传训练数据 训练模型 评测模型我的应用立即前往桂训练数据应用中心训练专属模型教程◎8应用服务上传训练数据 训练模型 评测模型我的应用 准备并上传SFT训练数据 通过多种方法进行模型微调训练 通过可视化工具进行全自动/半自动的评测应用广场:立即前往 立即前往 立即前桂应用体验中心创建专属RAG应用教程◎点击【创建新的API-KEY】，会自动创建一条属于这个账号的API-KEY。阿里云百炼大核型服务平台只←返回首页API KEY 管理API KEY创理新的API-KEY D API-KEY 创建时间 操作46098 sk-a****Qbil 2024-03-02 15:29:32 查看47982 sk-D****5EIA 2024-03-06 20:04:27 查看 除",
        "title": "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": "百炼平台的API-KEY创建步骤相对直接。首先，用户需登录百炼平台账号<ref>[1][4]</ref>，然后在页面右上角头像位置找到API-KEY入口<ref>[1]</ref>，点击后即可进入API-KEY管理页面。在此页面，用户可以点击“创建新的API-KEY”来生成专属于该账号的API-KEY<ref>[4]</ref>。\n\n获取API-KEY的方式主要是通过上述在线操作流程。一旦创建，API-KEY会在管理页面展示，用户可在此查看和管理它们<ref>[1][4]</ref>。\n\n关于API-KEY的权限范围，主要有以下规则：\n1. 主账号创建的API-KEY具有广泛权限，能访问所有业务空间下已被授权的资源<ref>[2]</ref>。\n2. 子账号创建的API-KEY仅限于访问该子账号有权限的业务空间内的已授权资源<ref>[2]</ref>。\n3. 子账号不能直接访问主账号业务空间（默认业务空间）下的资源，但可通过两种途径解决：一是请求主账号分享其API-KEY<ref>[2]</ref>；二是主账号授予子账号“主账号空间”管理员权限，使子账号间接访问主账号资源<ref>[2]</ref>。\n\n综上所述，API-KEY的创建和获取流程便捷，权限设计灵活且区分主子账号，确保了资源的安全可控。"
  },
  "usage": {
    "models": [
      {
        "model_id": "qwen-max",
        "input_tokens": 2004,
        "output_tokens": 313
      }
    ]
  },
  "request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}

若在应用的设置中开启了“展示回答来源”功能，模型生成的答复内容（即output.text）将附带角标<ref>[x1][x2]</ref>，以表明该部分内容是基于特定的引用信息制成的回答。这些具体的引用文本信息将被存储在output.doc_references中，而通过output.doc_references[x].index_id，角标索引x1、x2便能与它们所对应的引用信息建立链接。

异常响应示例

在访问请求出错的情况下，输出的结果中会通过 code 和 message 指明错误原因。

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

状态码说明

服务调用返回的状态码详情，请参见状态码说明。

上一篇：快速开始下一篇：SDK详情
文档推荐
  • 本页导读 （1）