Asynchronous Callbacks

When a task takes a long time or you don't want the client to block and wait, pass async=true and webhook_url to create an asynchronous task and receive a terminal-state callback.

Asynchronous callbacks are not a specific business endpoint, but rather the calling pattern of "any /v1 audio task endpoint + async=true + webhook_url". The example below demonstrates it with single-speaker speech POST /v1/audio/speech; other task endpoints work the same way.

Applicable scope

1. Create an API Key

   Open the API Key management platform, create an API Key, and save it as an environment variable. Do not write the API Key into client-side code or commit it to a repository.

   export MOSS_API_KEY="<your-api-key>"
   

2. Prepare the callback receiver

   Prepare a publicly accessible HTTPS endpoint to receive the terminal-state POST JSON callback for the task.

3. Send a request with async

   Add async=true and webhook_url to the request body of any task endpoint. The endpoint immediately returns a task object, the task moves into asynchronous processing, and the client is not blocked.

   {
     "model": "moss-tts",
     "input": "This is a piece of asynchronously generated speech.",
     "voice_id": "<voice_id>",
     "async": true,
     "webhook_url": "https://example.com/webhook"
   }
   

   curl https://api.mosi.cn/v1/audio/speech \
     -H "Authorization: Bearer $MOSS_API_KEY" \
     -H "Content-Type: application/json" \
     -d @request.json
   

4. Receive the terminal-state callback

   Once the task reaches a terminal state, MOSI sends a single POST JSON callback to webhook_url. The callback body is a compact terminal-state notification object (TaskID / TenantID / Status / CallbackURL) and does not contain the full task result; to obtain fields such as the result URL, use the TaskID from the callback to call the task query endpoint. For field details, see Callback Security Rules.

5. Fall back to active polling

   If you miss the callback, you can actively query using the task_id returned by the server: use GET /v1/audio/tasks/{task_id} for general audio tasks, and GET /v1/audio/transcriptions/{task_id} for transcription tasks.

Next steps