本文介绍通过OpenAI兼容接口 或 DashScopeAPI 调用通义千问OCR 模型的输入与输出参数。
如果模型调用失败并返回报错信息，请参见错误码进行解决。
相关文档：文字提取（Qwen-OCR）
OpenAI 兼容
- 华北2（北京）地域
- 新加坡地域
- 美国（弗吉尼亚）地域
SDK 调用配置的
base_url为：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1HTTP 调用配置的endpoint：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions您需要已获取与配置 API Key并配置API Key到环境变量。若通过OpenAI SDK进行调用，需要安装SDK。
请求体modelstring（必选）模型名称。支持的模型可参见选择模型。messagesarray（必选）传递给大模型的上下文，按对话顺序排列。
消息类型 User Message object（必选）用户消息，用于向模型传递指令和待识别的图像。
属性 content array（必选）消息内容。
属性 type string（必选）可选值：
string（可选）输入的文本。默认值为：Please output only the text content from the image without any additional descriptions or formatting. ，即模型默认提取图像中的全部文本。image_urlobject输入的图片信息。当type为image_url时是必选参数。
属性 url string（必选）图片的 URL或 Base64 Data URL。传入本地文件请参考文字提取。integer（可选）用于设定输入图像的最小像素阈值，单位为像素。当输入图像像素小于min_pixels时，会将图像进行放大，直到总像素高于min_pixels。
图像Token与像素的转换关系 不同模型，每个图像 Token 对应的像素不同：
min_pixels 取值范围
{"type": "image_url","image_url": {"url":"https://xxxx.jpg"},"min_pixels": 3072}max_pixelsinteger（可选）用于设定输入图像的最大像素阈值，单位为像素。当输入图像像素在[min_pixels, max_pixels]区间内时，模型会按原图进行识别。当输入图像像素大于max_pixels时，会将图像进行缩小，直到总像素低于max_pixels。
图像Token与像素的转换关系 不同模型，每个图像 Token 对应的像素不同：
max_pixels 取值范围
{"type": "image_url","image_url": {"url":"https://xxxx.jpg"},"max_pixels": 8388608}string（必选）用户消息的角色，固定为user。boolean（可选） 默认值为 false是否以流式方式输出回复。可选值：
object（可选）流式输出的配置项，仅在 stream 为 true 时生效。
属性 include_usage boolean（可选）默认值为 false是否在最后一个数据块包含Token消耗信息。可选值：
integer（可选）用于限制模型输出的最大 Token 数。若生成内容超过此值，响应将被截断。
boolean （可选）默认值为 false是否返回输出 Token 的对数概率，可选值：
integer （可选）默认值为0指定在每一步生成时，返回模型最大概率的候选 Token 个数。取值范围：[0,5]仅当 logprobs 为 true 时生效。temperaturefloat（可选）默认值为0.01采样温度，控制模型生成文本的多样性。temperature越高，生成的文本更多样，反之，生成的文本更确定。取值范围： [0, 2)temperature与top_p均可以控制生成文本的多样性，建议只设置其中一个值。建议设置为默认值即可。top_p float（可选）默认值为0.001核采样的概率阈值，控制模型生成文本的多样性。top_p越高，生成的文本更多样。反之，生成的文本更确定。取值范围：（0,1.0]temperature与top_p均可以控制生成文本的多样性，建议只设置其中一个值。建议设置为默认值即可。top_k integer（可选）默认值为1生成过程中采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top_k大于100时，表示不启用top_k策略，此时仅有top_p策略生效。取值需要大于或等于0。该参数非OpenAI标准参数。通过 Python SDK调用时，请放入 extra_body 对象中，配置方式为：extra_body={"top_k": xxx}；通过 Node.js SDK 或 HTTP 方式调用时，请作为顶层参数传递。建议设置为默认值即可。repetition_penalty float（可选）默认值为1.0模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。该参数对模型效果影响较大，建议保持默认值。建议设置为默认值即可。presence_penalty float（可选）默认值为0.0控制模型生成文本时的内容重复度。取值范围：[-2.0, 2.0]。正值降低重复度，负值增加重复度。在创意写作或头脑风暴等需要多样性、趣味性或创造力的场景中，建议调高该值；在技术文档或正式文本等强调一致性与术语准确性的场景中，建议调低该值。
原理介绍 如果参数值是正数，模型将对目前文本中已存在的Token施加一个惩罚值（惩罚值与文本出现的次数无关），减少这些Token重复出现的几率，从而减少内容重复度，增加用词多样性。 建议设置为默认值即可。seed integer（可选）随机数种子。用于确保在相同输入和参数下生成结果可复现。若调用时传入相同的 seed 且其他参数不变，模型将尽可能返回相同结果。取值范围：[0,2 31 −1]。建议设置为默认值即可。stop string 或 array（可选）用于指定停止词。当模型生成的文本中出现stop 指定的字符串或token_id时，生成将立即终止。可传入敏感词以控制模型的输出。stop为数组时，不可将 |
Python |
chat响应对象（非流式输出）idstring本次请求的唯一标识符。choicesarray模型生成内容的数组。
属性 finish_reason string模型停止生成的原因。有两种情况：
integer当前对象在choices数组中的索引。messageobject模型输出的消息。
属性 content string大模型的返回结果。processed_text string对模型原始输出进行后处理的结果，自动删除重复片段等。当模型输出存在重复内容时，该字段提供清洗后的文本。仅通过 DashScope SDK 和 curl 调用时返回，OpenAI 兼容 SDK 不返回该字段。refusal string该参数当前固定为null。role string消息的角色，固定为assistant。audio object该参数当前固定为null。function_call object该参数当前固定为null。tool_calls array该参数当前固定为null。integer本次请求被创建时的时间戳。modelstring本次请求使用的模型。object string始终为chat.completion。service_tier string该参数当前固定为null。system_fingerprintstring该参数当前固定为null。usage object本次请求的 Token 消耗信息。
属性 completion_tokens integer模型输出的 Token 数。prompt_tokens integer输入的 Token 数。total_tokens integer消耗的总 Token 数，为prompt_tokens与completion_tokens的总和。completion_tokens_details object模型输出Token的细粒度分类。
属性 accepted_prediction_tokens integer该参数当前固定为null。audio_tokens integer该参数当前固定为null。reasoning_tokens integer该参数当前固定为null。text_tokens integer模型输出文本对应的 Token 数。rejected_prediction_tokensinteger该参数当前固定为null。object输入 Token 的细粒度分类。
属性 audio_tokens integer该参数当前固定为null。cached_tokens integer该参数当前固定为null。text_tokens integer模型输入的文本对应的Token 数。image_tokens integer模型输入的图像对应的 Token数。 |
chat响应chunk对象（流式输出）idstring本次调用的唯一标识符。每个chunk对象有相同的 id。choicesarray模型生成内容的数组。若设置include_usage参数为true，则在最后一个chunk中为空。
属性 delta object流式返回的输出内容。
属性 content string大模型的返回结果。function_call object该参数当前固定为null。refusal object该参数当前固定为null。role string消息对象的角色，只在第一个chunk中有值。string模型停止生成的原因。有三种情况：
integer当前响应在choices数组中的索引。integer本次请求被创建时的时间戳。每个chunk有相同的时间戳。modelstring本次请求使用的模型。object string始终为chat.completion.chunk。service_tier string该参数当前固定为null。system_fingerprintstring该参数当前固定为null。usage object本次请求消耗的Token。只在include_usage为true时，在最后一个chunk返回。
属性 completion_tokens integer模型输出的 Token 数。prompt_tokens integer输入的 Token 数。total_tokens integer消耗的总 Token 数，为prompt_tokens与completion_tokens的总和。completion_tokens_details object模型输出Token的细粒度分类。
属性 accepted_prediction_tokens integer该参数当前固定为null。audio_tokens integer该参数当前固定为null。reasoning_tokens integer该参数当前固定为null。text_tokens integer模型输出文本对应的 Token 数。rejected_prediction_tokensinteger该参数当前固定为null。object输入 Token 的细粒度分类。
属性 audio_tokens integer该参数当前固定为null。cached_tokens integer该参数当前固定为null。text_tokens integer模型输入的文本对应的Token 数。image_tokens integer模型输入的图像对应的 Token数。 |
DashScope
- 华北2（北京）地域
- 新加坡地域
- 美国（弗吉尼亚）地域
HTTP 调用配置的
endpoint：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generationSDK 调用无需配置 base_url。您需要已获取与配置 API Key并配置API Key到环境变量。若通过DashScope SDK进行调用，需要安装DashScope SDK。
请求体modelstring（必选）模型名称。支持的模型可参见选择模型。messagesarray（必选）传递给大模型的上下文，按对话顺序排列。通过HTTP调用时，请将messages放入 input 对象中。
消息类型 User Message object（必选）用户消息，用于向模型传递问题、指令或上下文等。
属性 content string 或 array（必选）消息内容。若输入只有文本，则为 string 类型；若输入包含图像数据，则为 array 类型。
属性 text string（可选）输入的文本。默认值为：Please output only the text content from the image without any additional descriptions or formatting. ，即模型默认提取图像中的全部文本。imagestring（可选）图片的URL、 Base64 Data URL、或本地路径。传入本地文件请参见传入本地文件。示例值：{"image":"https://xxxx.jpeg"}enable_rotateboolean（可选）默认值为false是否对倾斜的图像进行校正处理。可选值：
{"image":"https://xxxx.jpeg","enable_rotate": True}min_pixelsinteger（可选）用于设定输入图像的最小像素阈值，单位为像素。当输入图像像素小于min_pixels时，会将图像进行放大，直到总像素高于min_pixels。
图像Token与像素的转换关系 不同模型，每个图像 Token 对应的像素不同：
min_pixels 取值范围
{"image":"https://xxxx.jpeg","min_pixels": 3072}max_pixelsinteger（可选）用于设定输入图像的最大像素阈值，单位为像素。当输入图像像素在[min_pixels, max_pixels]区间内时，模型会按原图进行识别。当输入图像像素大于max_pixels时，会将图像进行缩小，直到总像素低于max_pixels。
图像Token与像素的转换关系 不同模型，每个图像 Token 对应的像素不同：
max_pixels 取值范围
{"image":"https://xxxx.jpeg","max_pixels": 8388608}string（必选）用户消息的角色，固定为user。integer（可选）用于限制模型输出的最大 Token 数。若生成内容超过此值，响应将被截断。
Java SDK中为maxTokens*。*通过HTTP调用时，请将 max_tokens放入 parameters 对象中。ocr_optionsobject（可选）使用通义千问OCR模型调用内置任务时需要配置的参数。调用内置任务时，无需传入 User Message，模型内部会采用对应任务的Prompt。相关章节：调用内置任务。
属性 task string （必选）内置任务的名称，可选值如下：
object （可选）当task的取值为key_information_extraction（信息抽取）时，此参数用于指定需抽取的特定字段。如未指定 task_config，模型将默认提取图像中的所有字段。
属性 result_schema object （可选）表示需要模型抽取的字段，应为JSON对象结构，最多可嵌套3层JSON 对象。在JSON对象的键（key）中指定待抽取字段的名称，对应的值（value）可为空，建议在值中提供字段描述或格式要求，可提高信息提取的准确率。示例值：Java SDK为OcrOptions，DashScope Python SDK 最低版本为1.22.2， Java SDK 最低版本为2.18.4。 通过HTTP调用时，请将 ocr_options放入 parameters 对象中。seed integer（可选）随机数种子。用于确保在相同输入和参数下生成结果可复现。若调用时传入相同的 seed 且其他参数不变，模型将尽可能返回相同结果。取值范围：[0,2 31 −1]。建议设置为默认值即可。 通过HTTP调用时，请将 seed放入 parameters 对象中。temperature float（可选）默认值为0.01采样温度，控制模型生成文本的多样性。temperature越高，生成的文本更多样，反之，生成的文本更确定。取值范围： [0, 2)temperature与top_p均可以控制生成文本的多样性，建议只设置其中一个值。建议设置为默认值即可。 通过HTTP调用时，请将 temperature放入 parameters 对象中。top_p float（可选）默认值为0.001核采样的概率阈值，控制模型生成文本的多样性。top_p越高，生成的文本更多样。反之，生成的文本更确定。取值范围：（0,1.0]temperature与top_p均可以控制生成文本的多样性，建议只设置其中一个值。建议设置为默认值即可。 Java SDK中为topP*。*通过HTTP调用时，请将 top_p放入 parameters 对象中。top_k integer（可选）默认值为1生成过程中采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为None或当top_k大于100时，表示不启用top_k策略，此时仅有top_p策略生效。取值需要大于或等于0。该参数非OpenAI标准参数。通过 Python SDK调用时，请放入 extra_body 对象中，配置方式为：extra_body={"top_k": xxx}；通过 Node.js SDK 或 HTTP 方式调用时，请作为顶层参数传递。建议设置为默认值即可。repetition_penalty float（可选）默认值为1.0模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。该参数对模型效果影响较大，建议保持默认值。建议设置为默认值即可。 Java SDK中为repetitionPenalty*。*通过HTTP调用时，请将 repetition_penalty放入 parameters 对象中。presence_penalty float（可选）默认值为0.0控制模型生成文本时的内容重复度。取值范围：[-2.0, 2.0]。正值降低重复度，负值增加重复度。在创意写作或头脑风暴等需要多样性、趣味性或创造力的场景中，建议调高该值；在技术文档或正式文本等强调一致性与术语准确性的场景中，建议调低该值。
原理介绍 如果参数值是正数，模型将对目前文本中已存在的Token施加一个惩罚值（惩罚值与文本出现的次数无关），减少这些Token重复出现的几率，从而减少内容重复度，增加用词多样性。 建议设置为默认值即可。stream boolean（可选）默认值为false是否流式输出回复。参数值：
该参数仅支持Python SDK。通过Java SDK实现流式输出请通过incremental_output boolean（可选）默认为false在流式输出模式下是否开启增量输出。推荐您优先设置为true。参数值：
Java SDK中为incrementalOutput*。*通过HTTP调用时，请将 incremental_output放入 parameters 对象中。stop string 或 array（可选）用于指定停止词。当模型生成的文本中出现stop 指定的字符串或token_id时，生成将立即终止。可传入敏感词以控制模型的输出。stop为数组时，不可将logprobs boolean （可选）默认值为 false是否返回输出 Token 的对数概率，可选值：
通过HTTP调用时，请将 logprobs放入 parameters 对象中。top_logprobs integer （可选）默认值为0指定在每一步生成时，返回模型最大概率的候选 Token 个数。仅当 logprobs 为 true 时生效。取值范围：[0,5]Java SDK中为topLogprobs*。*通过HTTP调用时，请将 top_logprobs放入 parameters 对象中。 |
以下为调用高精识别内置任务的代码示例，详情请参见调用内置任务。 |
chat响应对象（流式与非流式输出格式一致）status_codestring本次请求的状态码。200 表示请求成功，否则表示请求失败。Java SDK不会返回该参数。调用失败会抛出异常，异常信息为status_code和message的内容。request_id string本次调用的唯一标识符。Java SDK返回参数为requestId。code string错误码，调用成功时为空值。只有Python SDK返回该参数。output object调用结果信息。
属性 text string该参数当前固定为null。finish_reasonstring模型结束生成的原因。有以下情况：
array模型的输出信息。
属性 finish_reason string有以下情况：
object模型输出的消息对象。
属性 role string输出消息的角色，固定为assistant。contentobject输出消息的内容。
属性 ocr_result object当Qwen-OCR系列模型调用内置的信息抽取、高精识别任务时，输出的任务结果信息。
属性 kv_result array信息抽取任务的输出结果。words_infoarray高精识别任务的输出结果。
属性 rotate_rect array示例值：[center_x, center_y, width, height, angle]文字框的旋转矩形表示：
array示例值：[x1, y1, x2, y2, x3, y3, x4, y4]文字框四个顶点的坐标，坐标顺序为左上角开起，按左上角→右上角→右下角→左下角的顺时针顺序排列。textstring文本行的内容string输出消息的内容。string对模型原始输出进行后处理的结果，自动删除重复片段等。当模型输出存在重复内容时，该字段提供清洗后的文本。object当前 choices 对象的概率信息。
属性 content array带有对数概率信息的 Token 数组。
属性 token string当前 Token。bytes array当前 Token 的 UTF‑8 原始字节列表，用于精确还原输出内容，在处理表情符号、中文字符时有帮助。logprob float当前 Token 的对数概率。返回值为 null 表示概率值极低。top_logprobs array当前 Token 位置最可能的若干个 Token 及其对数概率，元素个数与入参的top_logprobs保持一致。
属性 token string当前 Token。bytes array当前 Token 的 UTF‑8 原始字节列表，用于精确还原输出内容，在处理表情符号、中文字符时有帮助。logprob float当前 Token 的对数概率。返回值为 null 表示概率值极低。object本次请求使用的Token信息。
属性 input_tokens integer输入 Token 数。output_tokens integer输出 Token 数。characters integer该参数当前固定为0。input_tokens_detailsobject输入 Token 的细粒度分类。
属性 image_tokens integer模型输入的图像对应的 Token数。text_tokens integer模型输入的文本对应的Token 数。object输出 Token 的细粒度分类。
属性 text_tokens integer模型输入的文本对应的Token 数。integer消耗的总 Token 数，为input_tokens与output_tokens的总和。image_tokens integer输入内容包含image时返回该字段。为用户输入图片内容转换成Token后的长度。 |