CreateTask-阿里云帮助中心

Create offline transcription and real-time meeting tasks in Tingwu.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

tingwu:CreateTask

none

*All Resource

*

None

Request syntax

PUT /openapi/tingwu/v2/tasks HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
type	string	Yes	The type of the task. Valid values: offline: An offline task, such as an offline transcription. realtime: A real-time task, such as a real-time recording. Valid values: offline : offline realtime : realtime	offline
operation	string	No	The operation to perform. Valid values: start: Creates a task. This is the default value and does not typically need to be set. stop: Stops a real-time recording task. This value is used only for real-time tasks. To end the recording, set this parameter to `stop`. Valid values: stop : stop start : start	stop
body	object	No	The request body parameters.
AppKey	string	No	The AppKey of the project that you created in the console.	JV1sRTisRMi****
Input	object	No	The basic input parameters for creating a task. The required parameters vary based on the task type. For an offline task (`type="offline"`), you must specify the `SourceLanguage` and `FileUrl` parameters. For a real-time task (`type="realtime"`), you must also specify the `SourceLanguage`, `Format`, and `SampleRate` parameters.
SourceLanguage	string	Yes	The language model for speech transcription. The following values are supported: cn: Chinese en: English fspk: Chinese-English code-switching ja: Japanese yue: Cantonese Valid values: yue : Cantonese fspk : Chinese-English code-switching en : English cn : Chinese	cn
FileUrl	string	No	The HTTP or HTTPS URL of the source audio or video file. This parameter is required when you create an offline transcription task.	http://xxx.com/zzz/1.wav
TaskKey	string	No	A custom identifier that you can set for the task.	task_tingwu_123
Format	string	No	The encoding format of the audio stream data. This parameter is required when you create a real-time recording task. The following values are supported: pcm opus aac speex mp3 Valid values: pcm : pcm opus : opus	pcm
SampleRate	integer	No	The sample rate of the audio stream data. This parameter is required when you create a real-time recording task. The supported values are 8000 and 16000. 8000: Suitable for telephony and customer service scenarios. 16000: Suitable for real-time meeting audio capture scenarios. Valid values: 8000 : 8000 16000 : 16000	16000
ProgressiveCallbacksEnabled	boolean	No	Specifies whether to enable callbacks. To receive callbacks, you must configure the callback type and URL in the console and set this parameter to `true`.	false
MultipleStreamsEnabled	boolean	No	Specifies whether to enable multi-channel audio stream recognition. This parameter applies only to real-time recording scenarios. The default value is `false`.	false
TaskId	string	No	The task ID that is returned when you create a real-time recording. This ID is required to stop the recording. Specify this parameter only when stopping a real-time recording.	9922c84c087044eda18659c128b56c84
OutputPath	string	No
LanguageHints	array	No
	string	No
AudioChannelMode	string	No
Parameters	object	No	Algorithm-related parameters for customizing task processing.
Transcoding	object	No	Parameters for transcoding source audio/video files or audio streams.
TargetAudioFormat	string	No	Specifies the target format for the transcoded audio. Set to `mp3` to transcode the source audio into MP3 format for storage. This parameter is optional for offline transcription and real-time recording tasks.	mp3
TargetVideoFormat	string	No	Specifies the target format for the transcoded video. Set to `mp4` to transcode the source video into MP4 format for storage. This parameter applies only to offline transcription tasks with a video source file.	mp4
VideoThumbnailEnabled	boolean	No	Specifies whether to extract and save video thumbnails from the source video file. This parameter applies only to offline transcription tasks with a video source file.	false
SpectrumEnabled	boolean	No	Specifies whether to generate and save an audio waveform from the source audio/video file or audio stream. This parameter is optional for offline transcription and real-time recording tasks.	false
Transcription	object	No	Parameters to control the speech transcription process.
AudioEventDetectionEnabled	boolean	No	Specifies whether to enable sound event detection, which identifies non-speech events in the audio, such as music.	false
DiarizationEnabled	boolean	No	Specifies whether to enable speaker diarization.	false
Diarization	object	No	Parameters for the speaker diarization feature.
SpeakerCount	integer	No	Specifies the number of speakers to identify. If this parameter is not set, speakers are not differentiated in the transcript. Set the value to `0` to identify an unknown number of speakers. Set the value to `2` to identify two speakers. Valid values: 0 : 0 2 : 2	2
OutputLevel	integer	No	Specifies the level of detail for the speech transcription results. Default value: `1`. 1: Returns results only when a complete sentence is recognized. 2: Returns both intermediate and final results as they are recognized. Valid values: 1 : Returns results only when a complete sentence is recognized. 2 : Returns both intermediate and final results as they are recognized.	2
AdditionalStreamOutputLevel	integer	No	Specifies the level of detail for speech transcription results for the active speaker in a real-time recording scenario. 1: Returns results only when a complete sentence is recognized. 2: Returns both intermediate and final results as they are recognized. This parameter applies only to real-time recordings when `MultipleStreamsEnabled` is set to `true`. Valid values: 1 : Returns results only when a complete sentence is recognized. 2 : Returns both intermediate and final results as they are recognized.	1
PhraseId	string	No	The ID of the hotword list.	ce9c2a34b6d847bf92a77d0a196f****
Model	string	No
RealtimeDiarizationEnabled	boolean	No
ProfanityFilterEnabled	boolean	No
Translation	object	No	Parameters to control the translation feature.
TargetLanguages	array	No	The target languages for translation. This parameter is required if translation is enabled. Supported languages include Chinese, English, and Japanese.
	string	No	The target language for the translation. Valid values: cn: Chinese en: English ja: Japanese Valid values: ja : Japanese en : English cn : Chinese	en
OutputLevel	integer	No	Specifies the level of detail for real-time translation results. Default value: `1`. 1: Returns results only for complete sentences. 2: Returns both intermediate and final results. This parameter applies only to real-time recordings. Valid values: 1 : 1 2 : 2	2
AdditionalStreamOutputLevel	integer	No	Specifies the level of detail for real-time translation results for the active speaker. 1: Returns results only for complete sentences. 2: Returns both intermediate and final results. This parameter applies only to real-time recordings when `MultipleStreamsEnabled` is set to `true`. Valid values: 1 : Returns results only for complete sentences. 2 : Returns both intermediate and final results.	1
TranslationEnabled	boolean	No	Specifies whether to enable the translation feature.	false
AutoChaptersEnabled	boolean	No	Specifies whether to generate a chapter summary, which includes chapter titles and summaries for each chapter.	true
MeetingAssistanceEnabled	boolean	No	Specifies whether to generate intelligent minutes, which include keywords, key points, and action items.	false
MeetingAssistance	object	No	Parameters for the intelligent minutes feature, which supports processing for action items, keywords, and key points. If `MeetingAssistanceEnabled` is set to `true` but you do not specify this object, all analysis types are enabled by default.
Types	array	No	The types of analysis to perform when the intelligent minutes feature is enabled. Supported values: `Actions` (action items) and `KeyInformation` (key information, including keywords and key points).
	string	No	The type of analysis for intelligent minutes. Valid values: Actions: Extracts action items. KeyInformation: Extracts key information, including keywords and key points. Valid values: Actions : action item KeyInformation : Key information (including keywords and key points)	Actions
SummarizationEnabled	boolean	No	Specifies whether to enable the summarization feature, which can generate results such as a full-text summary and a speaker summary.	false
Summarization	object	No	Parameters for the summarization feature.
Types	array	No	The types of summaries to generate. This parameter is required when summarization is enabled. Supported types include `Paragraph` (full-text summary), `Conversational` (speaker summary), and `QuestionsAnswering` (Q&A summary). Valid values: Conversational : speaker summary QuestionsAnswering : Q&A summary Paragraph : full-text summary	Paragraph
	string	No	The type of summary to generate. Valid values: Paragraph: A full-text summary. Conversational: A speaker summary. QuestionsAnswering: A Q&A summary. Valid values: Conversational : speaker summary QuestionsAnswering : Q&A summary Paragraph : full-text summary	Paragraph
PptExtractionEnabled	boolean	No	Specifies whether to enable PPT extraction. If enabled, the service extracts slides from the video file and generates corresponding summaries. This feature applies only to offline transcription tasks with a video source file and has no effect on other task types.	false
TextPolishEnabled	boolean	No	Specifies whether to enable the spoken-to-written conversion feature.	false
ServiceInspectionEnabled	boolean	No
ServiceInspection	object	No
SceneIntroduction	string	No
InspectionIntroduction	string	No
InspectionContents	array<object>	No
	object	No
Title	string	No
Content	string	No
SpeakerMap	object	No
CustomPromptEnabled	boolean	No	Specifies whether to enable the custom prompt feature.	false
CustomPrompt	object	No	Parameters to control the custom prompt feature.
Contents	array<object>	No	A list of custom prompt parameters.
	object	No	An object that defines a single custom prompt.
Name	string	Yes	A custom name for the prompt, used to identify the corresponding output.	summary-demo
Prompt	string	Yes	The content of the custom prompt.	总结一下下面的对话内容:{Transcription}
Model	string	No	The model to use for the prompt.	tingwu-turbo
TransType	string	No	Specifies the format for the `{Transcription}` tag.	default
ExtraParams	object	No	Extended parameters for advanced use cases. You do not typically need to configure these parameters.
NfixEnabled	boolean	No	Specifies whether to enable nfix. You do not typically need to configure this parameter.	true
MaxKeywords	integer	No
DomainEducationEnabled	boolean	No
OcrAuxiliaryEnabled	boolean	No
TranslateLlmSceneEnabled	boolean	No
FullTextSummaryFormat	string	No
TranslationHotwordMap	object	No
bizUserId	string	No
bizType	string	No
ContentExtractionEnabled	boolean	No
ContentExtraction	object	No
SceneIntroduction	string	No
ExtractionContents	array<object>	No
	object	No
Title	string	No
Content	string	No
Identity	string	No
SpeakerMap	object	No
IdentityRecognitionEnabled	boolean	No
IdentityRecognition	object	No
SceneIntroduction	string	No
IdentityContents	array<object>	No
	object	No
Name	string	No
Description	string	No
AutoChapters	object	No
ChapterGranularity	string	No
Model	string	No
LlmOutputLanguage	string	No

Response elements

Element	Type	Description	Example
	object	The response schema.
RequestId	string	The request ID, used for troubleshooting only.	35124E1C-AE99-5D6C-A52E-BD689D8D****
Code	string	The status code.	0
Message	string	The status message.	Success.
Data	object	The response data.
TaskId	string	The task ID.	c5394c6ee0fb474899d42215a3925c7e
TaskKey	string	The custom identifier specified during task creation.	task_tingwu_123
MeetingJoinUrl	string	The stream ingestion URL. Push audio streams to this URL for real-time transcription.	wss://tingwu-realtime-cn-beijing.aliyuncs.com/api/ws/v1?mc=****
TaskStatus	string	The task status.	ONGOING

Examples

Success response

JSON format

{
  "RequestId": "35124E1C-AE99-5D6C-A52E-BD689D8D****",
  "Code": "0",
  "Message": "Success.",
  "Data": {
    "TaskId": "c5394c6ee0fb474899d42215a3925c7e",
    "TaskKey": "task_tingwu_123",
    "MeetingJoinUrl": "wss://tingwu-realtime-cn-beijing.aliyuncs.com/api/ws/v1?mc=****",
    "TaskStatus": "ONGOING"
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.