Skip to main content
Responses API

Synchronous API Reference

Synchronously invoke Alibaba Cloud Bailian applications via the OpenAI-compatible Responses API

This document describes how to synchronously invoke Alibaba Cloud Bailian applications (including Agent and Workflow applications) using the OpenAI-compatible Responses API. It is suitable for real-time interactive scenarios where you need immediate results, enabling seamless reuse of existing OpenAI codebases or rapid integration with tools from the OpenAI ecosystem.
This document applies only to legacy Agent applications (Agent 1.0). If you are using the new Agent applications (Agent 2.0), invoking the APIs described here will return a version-incompatibility error. For Agent 2.0, refer to the New Agent Application API.How to identify your application version: When creating an Agent application on the Application Management page, the system prompts you to select either Agent 2.0 (recommended) or Agent 1.0.
Related References

Prerequisites

  • You have obtained an API Key and configured it in your environment variables.
  • You have created an Alibaba Cloud Bailian application and retrieved its Application ID.
  • If invoking via SDK, you must also install the OpenAI Python SDK.

Endpoint

  • SDK base_url: https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/
  • HTTP Endpoint: POST https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/responses
Replace {APP_ID} with your actual Application ID.
Online Debugging: Navigate to the debugging interface via Application Card → Publish → API Debug, fill in the parameters, and click Run.

Quick Start: Send Your First Message

from openai import OpenAI
import os

api_key = os.getenv("DASHSCOPE_API_KEY")
app_id = 'APP_ID'  # Replace with your actual Application ID
base_url = f'https://dashscope.aliyuncs.com/api/v2/apps/agent/{app_id}/compatible-mode/v1/'

client = OpenAI(
    api_key=api_key,
    base_url=base_url
)

response = client.responses.create(
    input="Who are you?",
)

print(response.model_dump_json(indent=2))
When using the Python SDK and passing a simple string (e.g., input="Hello"), the SDK automatically wraps it into the full JSON structure required by the API. If you use cURL or another HTTP client directly, you must manually construct the complete JSON payload.

Request Parameters

ParameterTypeRequiredDescription
inputstring/arrayYesUser input content. Can be a plain string or an array of messages.
modelstringNoModel name — does not affect the actual model used for invocation.
streambooleanNoWhether to enable streaming output. Default: false.
previous_response_idstringNoThe ID of the previous response, used for multi-turn conversations.

Response Object

ParameterTypeDescription
idstringUnique identifier for this response.
outputarrayArray of output messages.
statusstringResponse status, e.g., completed.
usageobjectToken usage information.

Error Codes

If the call fails and returns an error message, consult the Responses API reference for troubleshooting.
Overview
Managed Agent API
Sandbox API
Memory API
Flow Agent API
RAG API
Connector API
Framework Integration
Assistant API (Deprecating)
  • Overview