tencent cloud

Feedback

DescribeTranscode

Last updated: 2023-12-07 10:46:36

    1. API Description

    Domain name for API request: tiw.tencentcloudapi.com.

    This API is used to query the progress and result of a document transcoding task.

    A maximum of 20 requests can be initiated per second for this API.

    We recommend you to use API Explorer
    Try it
    API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

    2. Input Parameters

    The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

    Parameter Name Required Type Description
    Action Yes String Common Params. The value used for this API: DescribeTranscode.
    Version Yes String Common Params. The value used for this API: 2019-09-19.
    Region Yes String Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-singapore.
    SdkAppId Yes Integer SdkAppId of the customer
    TaskId Yes String Unique ID of the document transcoding task

    3. Output Parameters

    Parameter Name Type Description
    Pages Integer Total number of document pages
    Progress Integer Transcoding progress. Value range: 0 to 100
    Resolution String Document resolution
    ResultUrl String URL of the transcoding result
    Dynamic transcoding: link of the HTML5 page transcoded from a PowerPoint file
    Static transcoding: URL prefix of the image transcoded for each document page. For example, if the URL prefix is http://example.com/g0jb42ps49vtebjshilb/, the image URL of the first page is
    http://example.com/g0jb42ps49vtebjshilb/1.jpg, and so on.
    Status String Current task state
    - QUEUED: queuing for transcoding
    - PROCESSING: transcoding is in progress
    - FINISHED: transcoded
    TaskId String Unique ID of the transcoding task
    Title String Document name
    ThumbnailUrl String URL prefix of the thumbnail. If the URL prefix is http://example.com/g0jb42ps49vtebjshilb/ , the thumbnail URL for the first page of the dynamically transcoded PowerPoint file is
    http://example.com/g0jb42ps49vtebjshilb/1.jpg, and so on.

    If the document transcoding request carries the ThumbnailResolution parameter and the transcoding type is dynamic transcoding, this parameter is not null. In other cases, this parameter is null.
    ThumbnailResolution String Resolution of the thumbnail generated for dynamic transcoding
    CompressFileUrl String URL for downloading the transcoded and compressed file. If CompressFileType carried in the document transcoding request is null or is not a supported compression format, this parameter is null.
    ResourceListUrl String Download URL (for trial) of the resource list.
    Note: This parameter may return null, indicating that no valid values can be obtained.
    Ext String Document generation mode (for trial).
    Note: This parameter may return null, indicating that no valid values can be obtained.
    CreateTime Integer Document transcoding task creation time, unit: seconds.
    Note: This parameter may return null, indicating that no valid values can be obtained.
    AssignTime Integer Document transcoding task assignment time, unit: seconds.
    Note: This parameter may return null, indicating that no valid values can be obtained.
    FinishedTime Integer Document transcoding task finished time, unit: seconds.
    Note: This parameter may return null, indicating that no valid values can be obtained.
    RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

    4. Example

    Example1 Querying a dynamic document transcoding task

    This example shows you how to query the result of a dynamic document transcoding task.

    Input Example

    POST / HTTP/1.1
    Host: tiw.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: DescribeTranscode
    <Common request parameters>
    
    {
        "TaskId": "g0jb42ps49vtebjshilb",
        "SdkAppId": "1400000001"
    }
    

    Output Example

    {
        "Response": {
            "Pages": 1,
            "Progress": 100,
            "RequestId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "Resolution": "793x1122",
            "ResultUrl": "https://transcode-result/0agdnligqtgtvkm65emb/index.html",
            "Status": "FINISHED",
            "TaskId": "0agdnligqtgtvkm65emb",
            "Title": "59378.docx",
            "ThumbnailUrl": "https://transcode-thumbnal/0agdnligqtgtvkm65emb/",
            "ThumbnailResolution": "793x1122",
            "CompressFileUrl": "",
            "ResourceListUrl": "https://transcode-result/0agdnligqtgtvkm65emb/resources.txt",
            "Ext": "Office"
        }
    }
    

    Example2 Querying a static document transcoding task

    This example shows you how to query the result of a static document transcoding task.

    Input Example

    POST / HTTP/1.1
    Host: tiw.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: DescribeTranscode
    <Common request parameters>
    
    {
        "TaskId": "g0jb42ps49vtebjshilb",
        "SdkAppId": "1400000001"
    }
    

    Output Example

    {
        "Response": {
            "Pages": 1,
            "Progress": 100,
            "RequestId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "Resolution": "793x1122",
            "ResultUrl": "https://transcode-result/0agdnligqtgtvkm65emb/",
            "Status": "FINISHED",
            "TaskId": "0agdnligqtgtvkm65emb",
            "Title": "59378.docx",
            "ThumbnailUrl": "",
            "ThumbnailResolution": "",
            "CompressFileUrl": "",
            "ResourceListUrl": "https://transcode-result/0agdnligqtgtvkm65emb/resources.txt",
            "Ext": "Office"
        }
    }
    

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    AuthFailure
    FailedOperation.FileDownloadFail Failed to download the document. To correct this, check whether the URL in the request parameter is correct. If you are using another file storage service, check the upload bandwidth of the file storage service. The document transcoding service supports downloading with a maximum duration of 1 minute. If the download fails, the transcoding request will also fail.
    FailedOperation.FileFormatError The document format is invalid. Read-only or encrypted documents cannot be transcoded.
    FailedOperation.FileOpenFail Failed to open the document. To correct this, check whether the document for transcoding is encrypted or encounters other format issues.
    FailedOperation.FileUploadFail Failed to upload the transcoding result. To correct this, try again later.
    FailedOperation.Transcode Failed to transcode. For more information, see the error description or contact our customer service.
    FailedOperation.TranscodeServerError The transcoding service encountered an internal error. Please try again later or contact our customer service.
    InvalidParameter.BodyParameterTypeUnmatched The parameter type does not match.
    InvalidParameter.FileFormatUnsupported The document extension is not supported.
    InvalidParameter.TaskNotFound The task to query does not exist.
    InvalidParameter.TranscodeParameter The document transcoding parameter format is invalid.
    InvalidParameter.UrlFormatError The document download URL format is invalid. To correct this, check the URL in the request parameter.
    LimitExceeded.TranscodePagesLimitation The number of pages exceeds the limit. Transcoding a file with more than 500 pages is currently unsupported. If you do need this feature, contact our customer service.
    ResourceUnavailable.NotRegistered TIW is not enabled.
    ResourceUnavailable.ServiceExpired The account is in arrears or the TIW service has expired.
    UnauthorizedOperation.SdkAppId The SdkAppId does not exist or does not match the current Tencent Cloud account.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support