Creating a Service Task¶

Function¶

This API is used to create a service task.

URI¶

POST /v1/{project_id}/services/{service_id}/tasks

**Table 1** Path Parameters¶
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details, see Obtaining a Project ID and Name.
service_id	Yes	String	Service ID

Request Parameters¶

**Table 2** Request body parameters¶
Parameter	Mandatory	Type	Description
name	Yes	String	Task name, which is mandatory. The value can contain 1 to 100 characters consisting of only letters, digits, hyphens (-), and underscores (_).
description	No	String	Task description, which is optional. The value contains a maximum of 500 characters.
schedule	No	TaskSchedule object	Configuration item of a scheduled task. This parameter is optional. Scheduled tasks do not support OBS input. URL input supports only RTMP and RTSP.
input	Yes	TaskInput object	Input configuration of a task. This parameter is mandatory.
output	Yes	TaskOutput object	Output configuration of a task. At least one output mode must be configured. ModelArts Edge supports webhook and dis. IEF supports obs, webhook, and dis.
config	No	Object	Algorithm configuration parameters specified during task running. This parameter is mandatory for some services. The value must be in JSON format. For details about the configuration items, see the description of the corresponding algorithm service. This parameter applies only to IEF. It cannot be used in ModelArts Edge.
source_usage_estimate	No	TaskSourceUsageEstimate object	Estimated resources to be used by the task. This parameter is mandatory for ModelArts Edge.

**Table 3** TaskSchedule¶
Parameter	Mandatory	Type	Description
type	Yes	String	Type of a scheduled task. This parameter is mandatory for scheduled tasks. The options are once (executed only once), daily (executed daily), weekly (executed weekly), and monthly (executed monthly). ModelArts Edge supports only once and daily.
execution_mode	No	String	Execution mode of a scheduled task. This parameter is mandatory for scheduled tasks. The value can be period (execution by period) or frequency (execution by frequency). ModelArts Edge supports only execution by period.
timezone	Yes	String	Time zone where a user is located. This parameter is mandatory for scheduled tasks. The value is accurate to the minute.
days_of_week	No	Array of integers	Days in a week when a task is executed. This parameter is mandatory only for weekly tasks. The values 1 to 7 indicate Monday to Sunday respectively.
days_of_month	No	Array of integers	Days in a month when a task is executed. This parameter is mandatory only for monthly tasks. The values 1 to 31 indicate the first day to the 31st day of a month.
periods	No	Array of periods objects	Period-based execution configuration. Use either this parameter or frequency. In this mode, at least one period must be specified.
frequency	No	frequency object	Frequency-based execution configuration. Use either this parameter or periods.

**Table 4** periods¶
Parameter	Mandatory	Type	Description
begin_at	Yes	String	Start time of a period. This parameter is mandatory. If a scheduled task is of the once type, the value of the parameter is in the format of yyyy-MM-ddThh:mm:ss. For other scheduled task types, the value of the parameter is in the format of hh:mm:ss.
end_at	Yes	String	End time of a period. This parameter is mandatory. If a scheduled task is of the once type, the value of the parameter is in the format of yyyy-MM-ddThh:mm:ss. For other scheduled task types, the value of the parameter is in the format of hh:mm:ss.

**Table 5** frequency¶
Parameter	Mandatory	Type	Description
interval	Yes	Integer	Interval between two consecutive executions. This parameter is mandatory when execution_mode is set to frequency. The value ranges from 5 to 720, in minutes.
duration	Yes	Integer	Duration for executing a single scheduled task. This parameter is mandatory when execution_mode is set to frequency. The value ranges from 5 to 720, in minutes.
begin_at	Yes	String	Start time of executions in a day. This parameter is mandatory. If a scheduled task is of the once type, the value of the parameter is in the format of yyyy-MM-ddThh:mm:ss. For other scheduled task types, the value of the parameter is in the format of hh:mm:ss.
end_at	Yes	String	End time of executions in a day. This parameter is mandatory. If a scheduled task is of the once type, the value of the parameter is in the format of yyyy-MM-ddThh:mm:ss. For other scheduled task types, the value of the parameter is in the format of hh:mm:ss.

**Table 6** TaskInput¶
Parameter	Mandatory	Type	Description
type	Yes	String	Input type of a task. This parameter is mandatory. ModelArts Edge supports the following types: restful (obtains the stream request URL from the custom streaming media server through the RESTful API), url (specified file address or stream request URL), edgecamera (edge camera bound to IEF), and vcn (VCN device). IEF supports the following types: restful, url, edgecamera, vcn, obs (files stored in OBS), and vis (video streams of VIS)
data	Yes	Array of TaskInputData objects	Input details of a task. This parameter is mandatory. The configuration varies according to the input type. Multiple inputs are allowed during creation, but only one input is allowed for update.
vcn	No	TaskInputVcn object	VCN server. This parameter is mandatory only when the input type is vcn.

**Table 7** TaskInputData¶
Parameter	Mandatory	Type	Description
stream_name	No	String	Name of a VIS video stream. This parameter is mandatory when the input type is vis.
bucket	No	String	OBS bucket name. This parameter is mandatory when the input type is obs.
path	No	String	OBS path. This parameter is mandatory when the input type is obs.
url	No	String	File URL or RESTful request URL for obtaining a video stream. This parameter is mandatory when the input type is url or restful. The value contains a maximum of 1000 characters.
headers	No	Object	Headers carried in the RESTful request for obtaining a video stream. This parameter is optional when the input type is restful. The value is key-value pairs in JSON format. A maximum of 10 key-value pairs are allowed.
certificate_check	No	Boolean	Whether to verify the certificate of the HTTPS request. This parameter is mandatory when the input type is restful. The value can be true or false.
rtsp_path_in_response	No	String	Video stream address in the response body for the RESTful request. This parameter is mandatory when the input type is restful. The value contains a maximum of 1024 characters.
node_id	No	String	Node ID. This parameter is required only for some services when the input type is restful or vcn.
device_id	No	String	VCN ID. This parameter is mandatory when the input type is vcn.
stream_type	No	Integer	Stream type used for analysis. This parameter is optional when the input type is vcn. The value ranges from 1 to 3. The value 1 indicates primary stream, the value 2 indicates secondary stream 1, and the value 3 indicates secondary stream 2.
id	No	String	ID of the mounted edge device. This parameter is mandatory when the input type is edgecamera.
camera_type	No	String	Camera type. This parameter is applicable to ModelArts Edge. When IPC cameras are used, set this parameter to ipc.
tag	No	Array of Map<String,String> objects	Camera tag. This parameter is mandatory when camera_type is set to ipc. This parameter is applicable to ModelArts Edge.

**Table 8** TaskInputVcn¶
Parameter	Mandatory	Type	Description
ip	Yes	String	IP address of a VCN server. This parameter is mandatory only when the input type is vcn.
port	Yes	Integer	Port number of a VCN server. This parameter is mandatory only when the input type is vcn.
username	Yes	String	Username for logging in to a VCN server. This parameter is mandatory only when the input type is vcn.
password	Yes	String	Password for logging in to a VCN server. This parameter is mandatory only when the input type is vcn.

**Table 9** TaskOutput¶
Parameter	Mandatory	Type	Description
obs	No	TaskOutputObs object	Configuration information when the output type is obs. This parameter cannot be used in ModelArts Edge.
dis	No	TaskOutputDis object	Configuration information when the output type is dis
webhook	No	TaskOutputWebhook object	Configuration information when the output type is webhook.

**Table 10** TaskOutputObs¶
Parameter	Mandatory	Type	Description
bucket	Yes	String	OBS bucket name. This parameter is mandatory when the obs type is used.
path	Yes	String	OBS path. This parameter is mandatory when the obs type is used.
data_category	No	Array of strings	List of task output types. This parameter is optional and is required only for some services. The output contains data in the dataCategory list.

**Table 11** TaskOutputDis¶
Parameter	Mandatory	Type	Description
stream_name	Yes	String	DIS stream name. This parameter is mandatory when the dis type is used.
data_category	No	Array of strings	List of task output types. This parameter is optional and is required only for some services. The output contains data in the dataCategory list.
stream_id	No	String	DIS stream ID. This parameter is applicable to ModelArts Edge.

**Table 12** TaskOutputWebhook¶
Parameter	Mandatory	Type	Description
url	Yes	String	Result callback address. This parameter is mandatory when the output type is webhook.
headers	Yes	Object	Headers carried in the result callback. This parameter is mandatory when the output type is webhook. The value is key-value pairs in JSON format. A maximum of 10 key-value pairs are allowed, and a minimum of 1 key-value pair is allowed.
data_category	No	Array of strings	List of task output types. This parameter is optional and is required only for some services. The output contains data in the dataCategory list.

**Table 13** TaskSourceUsageEstimate¶
Parameter	Mandatory	Type	Description
cpu	Yes	Float	Estimated CPU resources to be consumed by the task
memory	Yes	Integer	Estimated memory resources to be consumed by the task

Response Parameters¶

Status code: 201

**Table 14** Response body parameters¶
Parameter	Type	Description
tasks	Array of CreateResponseBody objects	Response body for creating a task

**Table 15** CreateResponseBody¶
Parameter	Type	Description
id	String	ID of the created service job

Status code: 400

**Table 16** Response body parameters¶
Parameter	Type	Description
error_code	String	Internal service error code
error_msg	String	Error message

Status code: 404

**Table 17** Response body parameters¶
Parameter	Type	Description
error_code	String	Internal service error code
error_msg	String	Error message

Example Requests¶

Create a common edge service task with restful as the input type and webhook as the output type.

/v1/b722xxxxxxxxxxxxxxxxxxxxxxeb4674/services/2a2db77f-xxxx-xxxx-xxxx-608a31865313/tasks

{
  "name" : "task-test",
  "description" : "hello world",
  "input" : {
    "type" : "restful",
    "data" : [ {
      "certificate_check" : false,
      "url" : "https://100.xx.xx.xx:xxxx",
      "rtsp_path_in_response" : "/input/url",
      "headers" : {
        "Content-Type" : "application/json"
      }
    } ]
  },
  "output" : {
    "webhook" : {
      "url" : "https://100.xx.xx.xx:xxxx/output",
      "headers" : {
        "Content-Type" : "application/json"
      }
    }
  },
  "source_usage_estimate" : {
    "cpu" : 0.1,
    "memory" : 32
  }
}

Create a common edge service task with edgecamera as the input type and DIS as the output type.

/v1/b722xxxxxxxxxxxxxxxxxxxxxxeb4674/services/2a2db77f-xxxx-xxxx-xxxx-608a31865313/tasks

{
  "name" : "task-test",
  "input" : {
    "type" : "edgecamera",
    "data" : [ {
      "id" : "hilens-c298xxxxxxxxxxxxxxxxxxxxxx8g5dc3",
      "camera_type" : "ipc",
      "tag" : [ {
        "tag1" : "hello1",
        "tag2" : "hello2"
      } ]
    } ]
  },
  "output" : {
    "dis" : {
      "stream_name" : "dis-test",
      "stream_id" : "154xxxxx171"
    }
  },
  "source_usage_estimate" : {
    "cpu" : 0.1,
    "memory" : 32
  }
}

Create a scheduled edge service task with url as the input type and DIS as the output type and executed from 08:00 a.m. to 08:00 p.m. (GTM+8:00) every day.

/v1/b722xxxxxxxxxxxxxxxxxxxxxxeb4674/services/2a2db77f-xxxx-xxxx-xxxx-608a31865313/tasks

{
  "name" : "task-test",
  "description" : "hello world",
  "input" : {
    "type" : "url",
    "data" : [ {
      "url" : "https://livestream.com/live/stream-test"
    } ]
  },
  "output" : {
    "dis" : {
      "stream_name" : "dis-test",
      "stream_id" : "xxxxxx"
    }
  },
  "schedule" : {
    "type" : "DAILY",
    "timezone" : "+08:00",
    "execution_mode" : "period",
    "periods" : [ {
      "begin_at" : "08:00:00",
      "end_at" : "20:00:00"
    } ]
  },
  "source_usage_estimate" : {
    "cpu" : 0.1,
    "memory" : 32
  }
}

Example Responses¶

Status code: 201

A service task is created.

{
  "tasks" : [ {
    "id" : "53e4xxxxxxxxxxxxxxxxxxxxxxb55b3e"
  } ]
}

Status code: 400

The request is invalid.

{
  "error_code" : "ModelArts.0101",
  "error_msg" : "Invalid argument. The field [input] is required and cannot be empty."
}

Status code: 404

The specified service does not exist.

{
  "error_code" : "ModelArts.3502",
  "error_msg" : "Service 2a2db77f-xxxx-xxxx-xxxx-608a31865313 does not exist."
}

Status Codes¶

Status Code	Description
201	A service task is created.
400	The request is invalid.
404	The specified service does not exist.

Error Codes¶

See Error Codes.

last updated: 2025-08-26 08:17 UTC - commit: 1ba1873d960563c60759f67898a855d9ba3c3502