Help Center/ Media Processing Center/ API Reference/ Animated GIF APIs/ Creating an Animated GIF Task
Updated on 2024-03-14 GMT+08:00
Online Debugging
CLI Examples
View PDF

Creating an Animated GIF Task

Function

This API is used to create an animated GIF task to convert a complete video file or part of a video file into an animated GIF file. Ensure that an input media file is stored in an OBS bucket in the same region as MPC and the permission for accessing the OBS bucket has been granted to MPC.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/animated-graphics

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID .

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token

The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Authorization

No

String

Authentication information. This parameter is mandatory when AK/SK-based authentication is used.

X-Project_Id

No

String

Project ID. This parameter is mandatory when AK/SK-based authentication is used. It is same as the project ID in path parameters.

X-Sdk-Date

No

String

Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

input

No

ObsObjInfo object

Input file information.

NOTE:

Videos in M3U8 format cannot be converted to animated GIFs, perform synchronous parsing or snapshot capturing.

output

No

ObsObjInfo object

Output file information

user_data

No

String

Custom user data

output_param

No

AnimatedGraphicsOutputParam object

Animated GIF parameter.
Table 4 ObsObjInfo

Parameter

Mandatory

Type

Description

bucket

Yes

String

OBS bucket name

location

Yes

String

Region where an OBS bucket is located. It must be the same as the region where MPC is deployed.

object

Yes

String

OBS object path, which complies with the OSS Object definition.

  • If this parameter is used for an input, an object must be specified.

  • If this parameter is used for an output, only the directory for storing the output needs to be specified.

file_name

No

String

File name

  • If this parameter is specified, the output object name is object/file_name.

  • If this parameter is not specified, the output object name is object/xxx, where xxx is specified by MPC.

When it is used as the output file name:

  • Specifies the name of the output file. This parameter is valid for packaging.

  • If the output file name needs to be specified during transcoding, use the output_filenames parameter.

  • This parameter is valid for parsing. If a file name is specified during parsing, the parsing parameters are written to the specified file name and the file metadata is obtained through the query API response in JSON format.

  • This parameter is invalid for snapshot capturing.

  • This parameter is invalid for conversion into animated GIFs.
Table 5 AnimatedGraphicsOutputParam

Parameter

Mandatory

Type

Description

format

Yes

String

Format of an output file. Currently, only GIF format is supported.

width

Yes

Integer

Width of an output animated file

The value is -1, 0, or a multiple of 2 from 32 to 3,840.

NOTE:

  • If this parameter is set to -1, width is adjusted based on height. In this case, height cannot be -1 or 0.

  • If this parameter is set to 0, the width of the input video is used. In this case, height can only be 0.

height

Yes

Integer

Height of an output animated file

The value is -1, 0, or a multiple of 2 from 32 to 2,160.

NOTE:

  • If this parameter is set to -1, height is adjusted based on width. In this case, width cannot be -1 or 0.

  • If this parameter is set to 0, the height of the input video is used. In this case, width can only be 0.

start

Yes

Integer

Start time Unit: ms

end

Yes

Integer

End time

Unit: ms

The maximum difference between end and start is 60 seconds.

frame_rate

No

Integer

Frame rate of the animated GIF.

Value range: 1 to 75

Response Parameters

Status code: 200

Table 6 Response body parameters

Parameter

Type

Description

task_id

String

Task ID.

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error description

Example Requests

Creates an animated GIF task to convert a complete video file or part of a video file into an animated GIF file.

POST https://{endpoint}/v1/{project_id}/animated-graphics

{
  "input" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/input.mp4"
  },
  "output" : {
    "bucket" : "example-bucket",
    "location" : "region01",
    "object" : "example-path/output",
    "file_name" : "test_mpc.gif"
  },
  "output_param" : {
    "format" : "gif",
    "width" : 480,
    "height" : 360,
    "frame_rate" : 15,
    "start" : 100,
    "end" : 250
  }
}

Example Responses

Status code: 200

Animated GIF task created successfully.

{
  "task_id" : 100211
}

Status code: 400

Failed to create an animated GIF task.

{
  "error_code" : "MPC.10202",
  "error_msg" : "Invalid request parameter."
}

Status Codes

Status Code

Description

200

Animated GIF task created successfully.

400

Failed to create an animated GIF task.

Error Codes

See Error Codes.

Parent Topic: Animated GIF APIs