Configure asynchronous task callbacks

Instead of polling for task results, you can configure an HTTP callback URL or RocketMQ to receive task completion notifications from EventBridge. Once notified, query the result API once to get the output.

Background

Alibaba Cloud Model Studio integrates with EventBridge to deliver task completion events to your configured event targets.

When an asynchronous task finishes (success or failure), a task completion event containing the task status and ID is reported to EventBridge, which forwards it to your target. For more event targets, see Event targets and Target service types.

Polling vs. event-driven notifications

Comparison dimension	Polling	Event-driven
Rate limiting	Result API is rate-limited (20 QPS)	No rate limiting
Integration complexity	Simple—poll the result API. Some tasks (such as text-to-image and text-to-video) provide SDKs with built-in polling.	Configure HTTP callback or RocketMQ in EventBridge and parse notifications.
Server resource consumption	Consumes server resources with frequent queries.	No resource consumption—EventBridge pushes to you.
Latency	Depends on polling interval.	Near real-time—pushed immediately on completion.
Recommendation	Low-concurrency or latency-tolerant scenarios.	High-concurrency or latency-sensitive scenarios.

Configure one of the following event targets in EventBridge:

HTTP callback URL: A publicly accessible or VPC endpoint that accepts POST requests. Suitable for most scenarios.
RocketMQ: Consume events via Message Queue for RocketMQ. Ideal for high-reliability scenarios.

Option 1: Configure an HTTP callback URL

Overview

After Alibaba Cloud Model Studio completes a task, it reports the task completion event to EventBridge. EventBridge then pushes this event to your callback endpoint. Your callback endpoint parses the event to extract the successfully processed task ID and calls the result query API once to retrieve the task output.

Benefits: Compared to direct polling, this approach avoids unnecessary polling requests, reduces resource consumption, and lowers pressure on the result query API’s rate limits.

Billing: EventBridge billing.

For example, the asynchronous invocation flow using an HTTP callback URL for text-to-image is as follows:

Create a text-to-image task and receive a task_id. The task is not yet complete.
After Alibaba Cloud Model Studio finishes processing, it reports the task completion event to EventBridge.
EventBridge proactively pushes the event to the HTTP callback endpoint.
The callback endpoint parses the event to obtain the completed task_id.
Finally, call the result query API to get the generated image URL.

Procedure

Step 1: Prepare the HTTP callback endpoint

Typically, deploy the HTTP callback endpoint in your business system to receive asynchronous event notifications. It must meet these requirements:

Request URL: An HTTP URL accessible over the public network or an Alibaba Cloud VPC.
Request method: POST.
Request body: JSON format containing the asynchronous task completion event data. You can view the exact event structure in the EventBridge console. Example:

Click to view the data structure of the asynchronous task completion event

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "xxxxx",
    "aliyunpublishtime": "2023-10-25T01:45:16.993Z",
    "data": {
        "start_time": "2023-10-25 09:45:09",
        "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-8k-v1",
        "task_status": "SUCCEEDED",
        "contain_result": false,
        "end_time": "2023-10-25 09:45:16",
        "task_id": "a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35",
        "region": "ap-southeast-1",
        "request_id": "108f38f5-xxxx-xxxx-xxxx-6504db9080b3",
        "api_key_id": "1250"
    },
    "aliyunoriginalaccountid": "xxxxxxxx",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "81765e5b-xxxx-xxxx-xxxx-bbad8dde2bd9",
    "source": "acs.dashscope",
    "time": "2023-1-25T01:45:16.969Z",
    "aliyunregionid": "ap-southeast-1",
    "type": "dashscope:System:AsyncTaskFinish"
}

Step 2: Query events in the EventBridge console

The EventBridge console lets you query events delivered by Alibaba Cloud Model Studio.

Log on to your Alibaba Cloud account and go to the EventBridge console. Switch to the Singapore region. In the navigation pane on the left, select Event buses and click default to enter the default event bus for cloud services.

Alibaba Cloud Model Studio uses the default event bus by default.
Click Event tracking and enter query conditions to find asynchronous task completion events from Alibaba Cloud Model Studio.
- Event source: Search for and select acs.dashscope, indicating the event originates from DashScope (the underlying model service of Alibaba Cloud Model Studio).
- Event type: Search for and select dashscope:System:AsyncTaskFinish, indicating an asynchronous task completion event.

Click Details to view the full details of the reported event.

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "xxxxx",
    "aliyunpublishtime": "2023-10-25T01:45:16.993Z",
    "data": {
        "start_time": "2023-10-25 09:45:09",
        "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-8k-v1",
        "task_status": "SUCCEEDED",
        "contain_result": false,
        "end_time": "2023-10-25 09:45:16",
        "task_id": "a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35",
        "region": "ap-southeast-1",
        "request_id": "108f38f5-xxxx-xxxx-xxxx-6504db9080b3",
        "api_key_id": "1250"
    },
    "aliyunoriginalaccountid": "xxxxxxxx",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "81765e5b-xxxx-xxxx-xxxx-bbad8dde2bd9",
    "source": "acs.dashscope",
    "time": "2023-1-25T01:45:16.969Z",
    "aliyunregionid": "ap-southeast-1",
    "type": "dashscope:System:AsyncTaskFinish"
}

Click to view parameter descriptions

Parameter	Type	Description	Example value
datacontenttype	String	Data format of the data field. Only `application/json` is supported.	`application/json;charset=utf-8`
aliyunaccountid	String	Alibaba Cloud account ID.	123456789098****
aliyunpublishtime	String	Time when the event was received.	2020-11-19T21:04:42.179PRC
data	Object	Event content. A JSON object whose structure is defined by the originating service. CloudEvents may include contextual information provided by the event producer at the time of occurrence, encapsulated within data.
data[].start_time	String	Asynchronous task start time. Format: yyyy-MM-dd HH:mm:ss	2023-10-25 09:45:09
data[].end_time	String	Asynchronous task completion time. Format: yyyy-MM-dd HH:mm:ss	2023-10-25 09:45:16
data[].user_api_unique_key	String	Unique API key (the five elements of the model API used when submitting the task). Format: `apikey:version:group:task:function-call:model` version: version group: group task: task name function-call: method name model: model name	`apikey:v1:audio:asr:transcription:paraformer-8k-v1`
data[].task_status	String	Task status PENDING: queued RUNNING: processing SUCCEEDED: Processing succeeded. FAILED: failed CANCELED: Task canceled UNKNOWN: task does not exist or status unknown	SUCCEEDED
data[].task_id	String	Task ID	a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35
data[].region	String	Region where the task runs	ap-southeast-1
data[].request_id	String	Request ID	108f38f5-xxxx-xxxx-xxxx-6504db9080b3
data[].api_key_id	String	API key ID	1234
aliyunoriginalaccountid	String	Original Alibaba Cloud account ID	123456789098****
specversion	String	CloudEvents protocol version	1.0
aliyuneventbusname	String	Name of the event bus that receives the event	default
id	String	Event ID—a unique value identifying the event.	45ef4dewdwe1-7c35-447a-bd93-fab****
source	String	Event source. The service that provides the event, identifying what occurred. It typically includes the event source type, publishing mechanism, or production process. The sender must ensure that each event’s `source+id` combination is unique.	acs.dashscope
time	String	Time when the event was generated. If the exact event time is unknown, CloudEvents producers may set time to another value (e.g., current time), but all producers for the same source must use consistent values.	2020-11-19T21:04:41+08:00
aliyunregionid	String	Region that receives the event.	ap-southeast-1
type	String	Event type. Describes the type of event related to the source. Used for routing, event queries, and policy enforcement. The format is defined by the producer and includes version information.	dashscope:System:AsyncTaskFinish

Step 3: Configure event forwarding rules

In the navigation pane on the left, select Event rules and click Create rule.
Configure basic information: Enter a custom rule name and description.
Configure event pattern: Specify which events to forward.
- Event source: Search for and select acs.dashscope, indicating the event originates from Alibaba Cloud Model Studio.
- Event type: Search for and select dashscope:System:AsyncTaskFinish, indicating an asynchronous task completion event.
- Pattern content: Configure filter conditions to match specific events. Use fields from the event details queried in Step 2. For pattern syntax, see Event patterns. Examples:
  - Default: After selecting the event source and type, the pattern defaults to the following, forwarding all dashscope:System:AsyncTaskFinish events.
```
{
  "source": ["acs.dashscope"],
  "type": ["dashscope:System:AsyncTaskFinish"]
}
```
  - Filter by field: Forward only events where the user_api_unique_key field ends with :paraformer-8k-v1—that is, only events for the paraformer-8k-v1 model. Event type is dashscope:System:AsyncTaskFinish.
```
{
  "source": ["acs.dashscope"],
  "type": ["dashscope:System:AsyncTaskFinish"],
  "data": {
    "user_api_unique_key": [
      {"suffix": ":paraformer-8k-v1"}
    ]
  }
}
```
Configure event targets: Supports multiple event target types, including HTTP callback URLs and RocketMQ message queues. See Step 4 for details.

Step 4: Set the event target to an HTTP callback endpoint

Configure event target: Forward events to an HTTP callback URL.
- Service type: Select “HTTP”.
- URL: Enter the HTTP service endpoint.
- Body: Select “Complete event”.
- Network type: Choose based on your service endpoint.
  - HTTP supports both public and private networks. If you select private network, configure VPC, vSwitch, and SecurityGroup.
Click Confirm to save the rule. If the event target shows an HTTP style, the configuration succeeded.

The rule’s Event target column now displays HTTP (1).

Option 2: Configure RocketMQ

Overview

After Alibaba Cloud Model Studio completes a task, it reports the task completion event to EventBridge. EventBridge forwards the event to Message Queue for RocketMQ. Your application listens to the message queue, consumes the message, extracts the completed task ID, and calls the result query API once to retrieve the task output.

Benefits: Unlike the HTTP callback approach, RocketMQ guarantees message delivery and supports retry on failure—ideal for scenarios requiring high message reliability.

Billing: EventBridge billing, RocketMQ billing.

For example, the asynchronous invocation flow using RocketMQ for text-to-image is as follows:

Create a text-to-image task and receive a task_id. The task is not yet complete.
After Alibaba Cloud Model Studio finishes processing, it reports the task completion event to EventBridge.
EventBridge proactively forwards the event to the specified RocketMQ queue.
Your application listens to the RocketMQ queue, consumes the message, and extracts the completed task_id.
Finally, call the result query API to get the generated image URL.

Procedure

Step 1: Prepare a RocketMQ instance (skip if you already have a RocketMQ queue)

To receive events via RocketMQ, first prepare a RocketMQ queue.

Go to the RocketMQ console. In the navigation pane on the left, select Instances and click Create Instance.

Instance ID example: rmq-cn-nwy*******.
Create a Topic for the instance and enter a custom topic name.
Create a Group for the instance and enter a custom group name.

Step 2: Query events in the EventBridge console

The EventBridge console lets you query events delivered by Alibaba Cloud Model Studio.

Log on to your Alibaba Cloud account and go to the EventBridge console. Switch to the Singapore region. In the navigation pane on the left, select Event buses and click default to enter the default event bus for cloud services.

Alibaba Cloud Model Studio uses the default event bus by default.
Click Event tracking and enter query conditions to find asynchronous task completion events from Alibaba Cloud Model Studio.
- Event source: Search for and select acs.dashscope, indicating the event originates from DashScope (the underlying model service of Alibaba Cloud Model Studio).
- Event type: Search for and select dashscope:System:AsyncTaskFinish, indicating an asynchronous task completion event.

Click Details to view the full details of the reported event.

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "xxxxx",
    "aliyunpublishtime": "2023-10-25T01:45:16.993Z",
    "data": {
        "start_time": "2023-10-25 09:45:09",
        "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-8k-v1",
        "task_status": "SUCCEEDED",
        "contain_result": false,
        "end_time": "2023-10-25 09:45:16",
        "task_id": "a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35",
        "region": "ap-southeast-1",
        "request_id": "108f38f5-xxxx-xxxx-xxxx-6504db9080b3",
        "api_key_id": "1250"
    },
    "aliyunoriginalaccountid": "xxxxxxxx",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "81765e5b-xxxx-xxxx-xxxx-bbad8dde2bd9",
    "source": "acs.dashscope",
    "time": "2023-1-25T01:45:16.969Z",
    "aliyunregionid": "ap-southeast-1",
    "type": "dashscope:System:AsyncTaskFinish"
}

Click to view parameter descriptions

Parameter	Type	Description	Example value
datacontenttype	String	Data format of the data field. Only `application/json` is supported.	`application/json;charset=utf-8`
aliyunaccountid	String	Alibaba Cloud account ID.	123456789098****
aliyunpublishtime	String	Time when the event was received.	2020-11-19T21:04:42.179PRC
data	Object	Event content. A JSON object whose structure is defined by the originating service. CloudEvents may include contextual information provided by the event producer at the time of occurrence, encapsulated within data.
data[].start_time	String	Asynchronous task start time. Format: yyyy-MM-dd HH:mm:ss	2023-10-25 09:45:09
data[].end_time	String	Asynchronous task completion time. Format: yyyy-MM-dd HH:mm:ss	2023-10-25 09:45:16
data[].user_api_unique_key	String	Unique API key (the five elements of the model API used when submitting the task). Format: `apikey:version:group:task:function-call:model` version: version group: group task: task name function-call: method name model: model name	`apikey:v1:audio:asr:transcription:paraformer-8k-v1`
data[].task_status	String	Task status PENDING: queued RUNNING: processing SUCCEEDED: Processing succeeded. FAILED: failed CANCELED: Task canceled UNKNOWN: task does not exist or status unknown	SUCCEEDED
data[].task_id	String	Task ID	a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35
data[].region	String	Region where the task runs	ap-southeast-1
data[].request_id	String	Request ID	108f38f5-xxxx-xxxx-xxxx-6504db9080b3
data[].api_key_id	String	API key ID	1234
aliyunoriginalaccountid	String	Original Alibaba Cloud account ID	123456789098****
specversion	String	CloudEvents protocol version	1.0
aliyuneventbusname	String	Name of the event bus that receives the event	default
id	String	Event ID—a unique value identifying the event.	45ef4dewdwe1-7c35-447a-bd93-fab****
source	String	Event source. The service that provides the event, identifying what occurred. It typically includes the event source type, publishing mechanism, or production process. The sender must ensure that each event’s `source+id` combination is unique.	acs.dashscope
time	String	Time when the event was generated. If the exact event time is unknown, CloudEvents producers may set time to another value (e.g., current time), but all producers for the same source must use consistent values.	2020-11-19T21:04:41+08:00
aliyunregionid	String	Region that receives the event.	ap-southeast-1
type	String	Event type. Describes the type of event related to the source. Used for routing, event queries, and policy enforcement. The format is defined by the producer and includes version information.	dashscope:System:AsyncTaskFinish

Step 3: Configure event forwarding rules

In the navigation pane on the left, select Event rules and click Create rule.
Configure basic information: Enter a custom rule name and description.
Configure event pattern: Specify which events to forward.
- Event source: Search for and select acs.dashscope, indicating the event originates from Alibaba Cloud Model Studio.
- Event type: Search for and select dashscope:System:AsyncTaskFinish, indicating an asynchronous task completion event.
- Pattern content: Configure filter conditions to match specific events. Use fields from the event details queried in Step 2. For pattern syntax, see Event patterns. Examples:
  - Default: After selecting the event source and type, the pattern defaults to the following, forwarding all dashscope:System:AsyncTaskFinish events.
```
{
  "source": ["acs.dashscope"],
  "type": ["dashscope:System:AsyncTaskFinish"]
}
```
  - Filter by field: Forward only events where the user_api_unique_key field ends with :paraformer-8k-v1—that is, only events for the paraformer-8k-v1 model. Event type is dashscope:System:AsyncTaskFinish.
```
{
  "source": ["acs.dashscope"],
  "type": ["dashscope:System:AsyncTaskFinish"],
  "data": {
    "user_api_unique_key": [
      {"suffix": ":paraformer-8k-v1"}
    ]
  }
}
```
Configure event targets: Supports multiple event target types, including HTTP callback URLs and RocketMQ message queues. See Step 4 for details.

Step 4: Set the event target to RocketMQ

After creating RocketMQ, open the event target configuration interface and select your RocketMQ instance.

Service type: Select “Message Queue for RocketMQ”.
Version: The RocketMQ version you created, such as RocketMQ 5.x.
Instance ID: The instance ID of your RocketMQ instance. See Step 1.
Topic: The topic name you created. See Step 1.

Step 5: View messages in the RocketMQ console

After configuration, submit an asynchronous task. Once complete, view the message in your configured RocketMQ topic.

To view messages online in RocketMQ, enable the one-click send/receive experience feature.
This feature uses Function Compute. If you exceed the free trial quota, minimal charges apply. See Function Compute billing rules.

On the Topics page, find your topic and click Details in the Actions column.

On the topic details page, switch to the One-click send/receive experience tab. In the Basic Features section, select a consumption method, such as PushConsumer.

After configuring parameters like Topic Name and Group ID, click Run to start receiving messages. The Run Results tab displays the received messages, including message ID and receipt time.

Step 6: Use the SDK to receive and consume messages

Use the RocketMQ Java SDK to implement the following logic: subscribe to the relevant topic and implement a message listener. Process the message upon receipt.

The following example shows Java client code for RocketMQ 5.0.

In a Maven project, add this dependency:

<dependency>
  <groupId>org.apache.rocketmq</groupId>
  <artifactId>rocketmq-client-java</artifactId>
  <version>5.0.4</version>
</dependency>

Example code for consuming MQ messages:

import com.alibaba.fastjson2.JSON;
import org.apache.rocketmq.client.apis.*;
import org.apache.rocketmq.client.apis.consumer.ConsumeResult;
import org.apache.rocketmq.client.apis.consumer.FilterExpression;
import org.apache.rocketmq.client.apis.consumer.FilterExpressionType;
import org.apache.rocketmq.client.apis.consumer.PushConsumer;
import org.apache.rocketmq.shaded.org.slf4j.Logger;
import org.apache.rocketmq.shaded.org.slf4j.LoggerFactory;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.Collections;

public class ConsumerExample {
    private static final Logger LOGGER = LoggerFactory.getLogger(ConsumerExample.class);

    private ConsumerExample() {
    }

    public static void main(String[] args) throws ClientException, IOException, InterruptedException {
        /*
          Endpoint obtained from the Endpoints tab on the instance details page in the console.
          If accessing from an Alibaba Cloud ECS instance over the internal network, use the VPC endpoint.
          If accessing from a local public network or on-premises IDC, use the public endpoint. Public endpoint access requires enabling public network access for the instance.
         */
        String endpoints = "xxxx";
        // Specify the target topic to subscribe to. The topic must be created in the console beforehand; otherwise, an error occurs.
        String topic = "xxxx";
        // Specify the consumer group for the consumer. The group must be created in the console beforehand; otherwise, an error occurs.
        String consumerGroup = "xxxx";
        final ClientServiceProvider provider = ClientServiceProvider.loadService();
        ClientConfigurationBuilder builder = ClientConfiguration.newBuilder().setEndpoints(endpoints);
        /*
          If using a public endpoint, configure the instance username and password, available on the instance details page in the console.
          If accessing from an Alibaba Cloud ECS instance over the internal network, skip this configuration—the server intelligently retrieves VPC info.
         */
        builder.setCredentialProvider(new StaticSessionCredentialsProvider("xxxx", "xxxx"));
        ClientConfiguration clientConfiguration = builder.build();
        // Subscription filter rule—subscribe to messages with any tag.
        String tag = "*";
        FilterExpression filterExpression = new FilterExpression(tag, FilterExpressionType.TAG);
        // Initialize PushConsumer with consumer group, communication parameters, and subscription relationship.
        PushConsumer pushConsumer = provider.newPushConsumerBuilder()
        .setClientConfiguration(clientConfiguration)
        // Set consumer group.
        .setConsumerGroup(consumerGroup)
        // Set pre-bound subscription relationships.
        .setSubscriptionExpressions(Collections.singletonMap(topic, filterExpression))
        // Set message listener.
        .setMessageListener(messageView -> {
            try {
                // Process message and return consumption result.
                ByteBuffer buffer = messageView.getBody();
                ByteBuffer newBuffer = ByteBuffer.allocate(buffer.capacity());
                for (int i = 0; i < buffer.capacity(); i++) {
                    newBuffer.put(buffer.get(i));
                }
                String result = new String(newBuffer.array());
                LOGGER.info("Consume message={}", JSON.toJSONString(result));
                System.out.println(result);
                return ConsumeResult.SUCCESS;
            } catch (Exception e) {
                LOGGER.error("deal message has error", e);
                return ConsumeResult.FAILURE;
            }
        })
        .build();
        Thread.sleep(Long.MAX_VALUE);

        // Close PushConsumer when no longer needed.
        pushConsumer.close();
    }
}

FAQ

Can one event rule have multiple event targets?

Yes. A single event rule can have multiple event targets. If configured, the same event is delivered to every target.

I configured an event rule but am not receiving events. Why?

Ensure the event forwarding rule’s region matches the event’s region. For example, a rule configured in the Singapore region only forwards Singapore events—not other regions. Check the EventBridge region in the region selector at the top of the console page.

HTTP/HTTPS service request times out or returns an error?

Follow these steps to troubleshoot:

Check the HTTP/HTTPS service status.
Verify the URL configured in the event target.
Check the network type configured for the event target:
- PublicNetwork: Public network—ensure the URL is publicly accessible.
- PrivateNetwork: VPC network—if selected, verify VPC, vSwitch, and SecurityGroup configurations.
  - Check VPC and vSwitch settings.
  - Check network security group settings.
For other parameter settings, see Event target parameters.