文档中心

接口文档-异步任务

最近更新时间：2023.07.05 15:29:55

首次发布时间：2023.07.04 20:23:22

本文档意在向用户说明如何在创建【异步任务】后，通过调用平台接口【提交图片&视频数据】

1. 名词解析

AK&SK	火山引擎账号API访问控制秘钥
TOP	网关服务，通过TOP网关请求此接口

2. 图片提交接口

请求地址	https://open.volcengineapi.com?Action=AddAsyncTaskImageData&Version=2022-05-13
请求方法	POST

2.1 Request header

参数	类别	是否必填	描述
Region	string	是	cn-north-1
Service	string	是	iva
Content-Type	string	是	multipart/form-data

2.2 Request body

注意此处因涉及文件上传，body格式不再是【json】而是【multipart/form-data】

参数	类别	是否必填	描述
Request	string	是	Json 格式字符串，具体内容见下文
ImageFile	FILE	否	任务图片数据，单张图片大小不超过50M

2.2.1 Request

参数	类别	是否必填	描述
TaskID	string	是	任务ID
Image	imageInfo	是	结构体，见下表
AlgoParamConf	map[string]interface{}	否	自定义算法参数说明

2.2.2 imageInfo

参数	类别	是否必填	描述
Name	string	是	图片名称
Source	string	是	枚举：url、file url：图片url，从Url字段中获取图片 file：表单上传图片文件，为此字段时，从表单File中获取图片
Url	string	否	图片url
Desc	string	否	图片描述

2.3 Response body

{
    "ResponseMetadata": {
        "RequestId": "20220214145936010211209131054BC6F2",
        "Action": "{Action}",
        "Version": "{Version}",
        "Service": "{Service}",
        "Region": "{Region}",
        "Error": { // 优先检测此字段，请求参数校验不通过时，会有相应信息
            "Code": "{ErrorCode}",
            "Message": "{ErrorMessage}"
        }
    },
    "Result":{
        "ImageID":"xxxx-xxxx"
    }
}

3. 图片接口请求Demo

package main

import (
   "bytes"
   "encoding/json"
   "fmt"
   "github.com/volcengine/volc-sdk-golang/base"
   "io"
   "io/ioutil"
   "mime/multipart"
   "net/http"
   "net/url"
   "os"
)

var (
    ak string
    sk string
)

fumc main() {

    ak = "your_volc_ak"
    sk = "your_volc_sk"
    
    imgFile, err := os.Open("tesst.jpg") // 本地图片文件
    if err != nil {
        panic(err)
    }
    
    // 通过文件上传
    addAsyncTaskImageData(&addImageDataReq{
        TaskID: "xxx-xxxx-xxxx", // 填写创建同步任务返回的任务ID
        Image: imageInfo{
            Name: "xxxx",
            Source: "file",
            Desc: "desc"
        },
    },imgFile)
    
    // 通过url上传
    addAsyncTaskImageData(&addImageDataReq{
        TaskID: "xxx-xxxx-xxxx", // 填写创建异步任务返回的任务ID
        Image: imageInfo{
            Name: "xxxx",
            Source: "url",
            Url:"https://xxx.xxx.xx/xxx.jpg" // 图片文件url
            Desc: "desc"
        },
    },nil)
}

type imgInfo struct {
   Name   string `json:"Name" vd:"@:len($)>0; msg:'image name can not be null'"`
   Source string `json:"Source"`
   Url    string `json:"Url"`
   Desc   string `json:"Desc"`
}

type addImageDataReq struct {
   TaskID        string                 `json:"TaskID,required" vd:"@:len($)>0; msg:'task id can not be null'"`
   Image         imgInfo                `json:"Image,required"`
   AlgoParamConf map[string]interface{} `json:"AlgoParamConf"`
}

type addImageDataResult struct {
   ImageID     string   `json:"ImageID"`
}

type addImageDataResp struct {
   ResponseMetadata baseResp           `json:"ResponseMetadata"`
   Result           addImageDataResult `json:"Result"`
}

func addAsyncTaskImageData(aidr *addImageDataReq, file *os.File) {
   query := url.Values{
      "Action":  []string{"AddAsyncTaskImageData"},
      "Version": []string{"2022-05-13"},
   }

   u := url.URL{
      Scheme:   "https",
      Host:     "open.volcengineapi.com",
      RawQuery: query.Encode(),
   }

   paramBytes, err := json.Marshal(aidr)
   if err != nil {
      panic(err)
   }

   reqBody := &bytes.Buffer{}
   writer := multipart.NewWriter(reqBody)
   if file != nil {
      fileWriter, err := writer.CreateFormFile("ImageFile", file.Name())
      if err != nil {
         panic(err)
      }
      _, err = io.Copy(fileWriter, file)
      if err != nil {
         panic(err)
      }
   }
   err = writer.WriteField("Request", string(paramBytes))
   if err != nil {
      panic(err)
   }
   writer.Close()

   req, err := http.NewRequest(http.MethodPost, u.String(), reqBody)
   if err != nil {
      panic(err)
   }
   req.Header.Set("Region", topRegion)
   req.Header.Set("Service", topService)
   req.Header.Set("Content-Type", writer.FormDataContentType())

   credentials := base.Credentials{
      AccessKeyID:     ak,
      SecretAccessKey: sk,
      Service:         req.Header.Get("Service"),
      Region:          req.Header.Get("Region"),
   }
   credentials.Sign(req) // 请求签名

   resp, err := http.DefaultClient.Do(req)
   if err != nil {
      panic(err)
   }

   if resp.StatusCode != http.StatusOK {
      panic(resp.Status)
   }

   body, err := ioutil.ReadAll(resp.Body)
   resp.Body.Close()
   if err != nil {
      panic(err)
   }

   r := &addImageDataResp{}
   err = json.Unmarshal(body, r)
   if err != nil {
      panic(err)
   }
   fmt.Printf("addAsyncTaskImageData Resp: %+v\n", r)

}

4. 视频提交接口

请求地址	https://open.volcengineapi.com?Action=AddAsyncTaskVideoData&Version=2022-05-13
请求方法	POST

4.1 Request header

参数	类别	是否必填	描述
Region	string	是	cn-north-1
Service	string	是	iva
Content-Type	string	是	multipart/form-data

4.2 Request body

注意此处因涉及文件上传，body格式不再是【json】而是【multipart/form-data】

参数	类别	是否必填	描述
Request	string	是	Json 格式字符串，具体内容见下文
VideoFile	FILE	否	视频数据

4.2.1 Request

参数	类别	是否必填	描述
TaskID	string	是	任务ID
Video	videoInfo	是	结构体，见下表
AlgoParamConf	map[string]interface{}	否	自定义算法参数说明

4.2.2 videoInfo

参数	类别	是否必填	描述
Name	string	是	视频名称
Source	string	是	枚举：url、file url：视频url，从Url字段中获取视频 file：表单上传视频文件，为此字段时，从表单File中获取视频
Url	string	否	视频url
Desc	string	否	视频描述

4.3 Response body

{
    "ResponseMetadata": {
        "RequestId": "20220214145936010211209131054BC6F2",
        "Action": "{Action}",
        "Version": "{Version}",
        "Service": "{Service}",
        "Region": "{Region}",
        "Error": { // 优先检测此字段，请求参数校验不通过时，会有相应信息
            "Code": "{ErrorCode}",
            "Message": "{ErrorMessage}"
        }
    },
    "Result":{
        "VideoID":"xxxx-xxxx"
    }
}

5. 视频接口请求Demo

package main

import (
   "bytes"
   "encoding/json"
   "fmt"
   "github.com/volcengine/volc-sdk-golang/base"
   "io"
   "io/ioutil"
   "mime/multipart"
   "net/http"
   "net/url"
   "os"
)

var (
    ak string
    sk string
)

fumc main() {

    ak = "your_volc_ak"
    sk = "your_volc_sk"
    
    videoFile, err := os.Open("tesst.mp4") // 本地视频文件
    if err != nil {
        panic(err)
    }
    
    // 通过文件上传
    addAsyncTaskVideoData(&addVideoDataReq{
        TaskID: "xxx-xxxx-xxxx", // 填写创建异步任务返回的任务ID
        Video: videoInfo{
            Name: "xxxx",
            Source: "file",
            Desc: "desc"
        },
    },videoFile)
    
    // 通过url上传
    addAsyncTaskVideoData(&addVideoDataReq{
        TaskID: "xxx-xxxx-xxxx", // 填写创建异步任务返回的任务ID
        Video: videoInfo{
            Name: "xxxx",
            Source: "url",
            Url:"https://xxx.xxx.xx/xxx.mp4" // 视频文件url
            Desc: "desc"
        },
    },)
}

type videoInfo struct {
   Name   string `json:"Name" vd:"@:len($)>0; msg:'video name can not be null'"`
   Source string `json:"Source"`
   Url    string `json:"Url"`
   Desc   string `json:"Desc"`
}

type addVideoDataReq struct {
   TaskID        string                 `json:"TaskID,required" vd:"@:len($)>0; msg:'task id can not be null'"`
   Video         videoInfo              `json:"Video,required"`
   AlgoParamConf map[string]interface{} `json:"AlgoParamConf"`
}

type addVideoDataResult struct {
   VideoID     string   `json:"VideoID"`
}

type addVideoDataResp struct {
   ResponseMetadata baseResp           `json:"ResponseMetadata"`
   Result           addVideoDataResult `json:"Result"`
}

func addAsyncTaskVideoData(avdr *addVideoDataReq, file *os.File) {
   query := url.Values{
      "Action":  []string{"AddAsyncTaskVideoData"},
      "Version": []string{"2022-05-13"},
   }

   u := url.URL{
      Scheme:   "https",
      Host:     "open.volcengineapi.com",
      RawQuery: query.Encode(),
   }

   paramBytes, err := json.Marshal(avdr)
   if err != nil {
      panic(err)
   }

   reqBody := &bytes.Buffer{}
   writer := multipart.NewWriter(reqBody)
   if file != nil {
      fileWriter, err := writer.CreateFormFile("VideoFile", file.Name())
      if err != nil {
         panic(err)
      }
      _, err = io.Copy(fileWriter, file)
      if err != nil {
         panic(err)
      }
   }
   err = writer.WriteField("Request", string(paramBytes))
   if err != nil {
      panic(err)
   }
   writer.Close()

   req, err := http.NewRequest(http.MethodPost, u.String(), reqBody)
   if err != nil {
      panic(err)
   }
   req.Header.Set("Region", topRegion)
   req.Header.Set("Service", topService)
   req.Header.Set("Content-Type", writer.FormDataContentType())

   credentials := base.Credentials{
      AccessKeyID:     ak,
      SecretAccessKey: sk,
      Service:         req.Header.Get("Service"),
      Region:          req.Header.Get("Region"),
   }
   credentials.Sign(req) // 请求签名

   resp, err := http.DefaultClient.Do(req)
   if err != nil {
      panic(err)
   }

   if resp.StatusCode != http.StatusOK {
      panic(resp.Status)
   }

   body, err := ioutil.ReadAll(resp.Body)
   resp.Body.Close()
   if err != nil {
      panic(err)
   }

   r := &addVideoDataResp{}
   err = json.Unmarshal(body, r)
   if err != nil {
      panic(err)
   }
   fmt.Printf("addAsyncTaskVideoData Resp: %+v\n", r)

}

6. 备注

异步任务处理的结果通过回调的方式给出