AI 视频
发布时间:2023-09-05 18:09
版本 | 说明 | 修订人 | 修订日期 |
---|---|---|---|
v1 | 1. 修改 channel 渠道为不必填2. jobParams.userID 为不必填3. jobParams 加入 title 字段 4. jobParams 加 layoutType 字段 5. 字段一致性:作业id 统一为 jobID 6. 提交合成作业API 改为 /api/aigc/v1/job/submitJob |
时一博 | 2023-7-5 |
v1 | 提交合成作业接口加入 isNotReproduce 字段 |
时一博 | 2023-7-28 |
v1 | 提交合成参数加入 bgAudio 、 narration 、subtitle 、background 、opening 、ending 、logo 字段 |
时一博 | 2023-9-5 |
⼀、 前置条件
⼆、API公共请求参数
三、提交 AI 合成作业接口
HTTP 协议
使用 HTTPS 进行调用。
请求地址
/api/aigc/v1/job/submitJob
请求方法
HTTP POST
方法
请求参数
Headers 头:
参数名称 | 参数值 | 是否必须 | 示例值 | 说明 |
---|---|---|---|---|
Content-Type |
application/x-www-form-urlencoded | 是 |
Body
参数名称 | 类型 | 是否必填 | 示例值 | 说明 |
---|---|---|---|---|
outJobID |
string | 否 | 342183803713748992 | 三方 job id ,使用方保持唯一,长度不要超过128 |
notifyUrl |
string | 否 | callback 路径,回调使用,如果填写,回调 七、回调机制 | |
jobParams |
string | 是 | job 作业参数,json 对象,包含作业相关参数,见作业参数 (表2) |
作业参数 (表2) :
参数名称 | 类型 | 是否必填 | 示例值 | 说明 |
---|---|---|---|---|
content |
string | 是 | 正文内容 | |
title |
string | 否 | 三国演义 | 标题, 1、 如为空,会自动填充 2、不为空,长度不能超过40字 |
ext |
string(json 对象字符串) | 否 | “ext”:“{"id":"12345"}” | 扩展字段,如有内容,在回调的时候透传给调用方 |
userID |
string | 否 | 用户id | |
layoutType |
int | 否 | 1 | 视频比例值有1、2 1 : 横版 16:9 2: 竖版 9:16 |
isNotReproduce |
bool | 否 | false | 当多次请求使用相同的 OutJobID 字段值时: 1. 如果 isNotReproduce 为 true,且 content、title 字段值与最近一次作业对应字段值相同时,则返回最近一次 JobID 和作业状态;否则返回相应错误信息。 2. 如果 isNotReproduce 为 false,则表示重新处理作业并扣除对应点数 |
bgAudio |
object | 否 | 背景音乐,详见获取背景音乐列表 | |
- audioID |
string | 是 | 音频数据id | |
- bgAudioID |
string | 是 | 背景音乐id | |
- volume |
int | 否 | 50 | 音量 0~100 之间数值 |
narration |
object | 配音,详见获取配音列表 | ||
- narratorID |
string | 是 | 配音 id | |
- key |
string | 是 | 样音key | |
- speedFloat |
string | 否 | 语速 0.8:最慢 0.9:慢 1: 正常 1.1:较快 1.3:快 1.5:最快 |
|
- volume |
int | 否 | 音量 0~100 之间数值 | |
subtitle |
object | 否 | 字幕,详见获取字幕风格列表 | |
- subtitleID |
string | 是 | 字幕样式id | |
- isHidden |
bool | 否 | 是否隐藏字幕 false: 不隐藏 true:隐藏 | |
background |
object | 否 | 背景,详见获取背景列表 | |
- templateID |
string | 是 | 背景 id | |
opening |
object | 否 | 片头,详见获取用户素材列表, 需要在 一帧秒创-我的素材 上传视频、图片 | |
- mediaID |
string | 是 | 素材id | |
- materialType |
int | 是 | 素材类型 1:视频 2:图片 | |
- startTime |
int | 开始时间(毫秒) | ||
- endTime |
int | 结束时间(毫秒) | ||
ending |
object | 否 | 片尾,详见获取用户素材列表, 需要在 一帧秒创-我的素材 上传视频、图片 | |
- mediaID |
string | 是 | 素材id | |
- materialType |
int | 是 | 素材类型 1:视频 2:图片 | |
- startTime |
int | 否 | 开始时间(毫秒) | |
- endTime |
int | 否 | 结束时间(毫秒) | |
logo |
object | 否 | logo,详见获取 Logo 模板列表 | |
- templateID |
string | 是 | Logo 模板id | |
- isHidden |
bool | 否 | 是否隐藏logo false: 不隐藏 true:隐藏 |
返回参数
名称 | 类型 | 默认值 | 说明 |
---|---|---|---|
code |
int | 1 | 1 为成功, 非 1 为失败,具体错误码见响应码 |
msg |
string | SUCCESS | |
devMsg |
string | 开发调试使用 | |
data |
object | 数据对象,json 对象。 | |
- jobID |
string | 作业id | |
requestID |
string | 请求id |
响应码
http 响应码 统一 为 200,具体 业务错误码 见 “五、错误码” 章节
调用示例
请求示例
curl --location 'openapi.yizhentv.com/api/aigc/v1/job/submitJob' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'appID={应用id}' \
--data-urlencode 'date=2023-7-5 18:22:50' \
--data-urlencode 'nonce=2cc80238-37e8-4a99-b803-eb0e2620eb2b' \
--data-urlencode 'signType=HMAC-SHA1' \
--data-urlencode 'signature={签名}' \
--data-urlencode 'outJobID=123' \
--data-urlencode 'jobParams={"title":"老师,你好","content":"我敬爱的老师,你好,你最近过的怎么样?","layoutType":2,"bgAudio":{"audioID":"123","bgAudioID":"927","volume":10,"startTime":1000,"endTime":-1},"narration":{"narratorID":"38","key":"123sdf","speedFloat":"1","volume":40},"subtitle":{"subtitleID":9,"isHidden":false},"background":{"templateID":"123"},"opening":{"mediaID":"123","materialType":1,"endTime":1000},"ending":{"mediaID":"123","materialType":2,"endTime":1000},"logo":{"templateID":"53","isHidden":false}}'
返回示例
{
"code": 1,
"msg": "SUCCESS",
"data": {
"jobID": "148012817451843584"
},
"requestID": "539BA2BA-CF8C-4D8F-8AB0-1BD9FDCD0F2B"
}
四、查询 AI 合成作业接口
HTTP 协议
使用 HTTPS 进行调用。
请求地址
/api/aigc/job/getJobs
请求方法
HTTP POST
方法
请求参数
Headers 头
参数名称 | 参数值 | 是否必须 | 示例值 | 说明 |
---|---|---|---|---|
Content-Type |
application/x-www-form-urlencoded | 是 |
Body
参数名称 | 类型 | 是否必填 | 示例值 | 说明 |
---|---|---|---|---|
jobID |
string | 是 | NQIAO0PNSYHX5DJJVRYUP | 作业id,查询合成作业信息使用 |
返回参数
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
code |
int | 是 | 1 为成功,非 1 为失败,具体错误码见响应码 | |
msg |
string | 是 | ||
devMsg |
string | 否 | 开发调试使用 | |
data |
object | 是 | 数据对象,json 对象 | |
- jobID |
string | 是 | 作业id | |
- jobId |
integer | 否 | 作业id遗弃,请使用 jobID | |
- covers |
array | 是 | 封面图 url 地址,默认第一个是封面图 | |
- video |
string | 是 | 视频 url 地址,有效期为 6 个小时,需要在及时同步走视频。 | |
- state |
int | 作业状态 1 : 作业待运行2: 作业运行中3: 作业运行成功4: 作业运行失败 | ||
requestID |
string | 是 | 请求id |
响应码
http 响应码 统一 为 200,具体 业务错误码 见 “五、错误码 章节
调用示例
请求示例
curl --location 'http://openapi.yizhentv.com/api/aigc/job/getJobs' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'appID={应用id}' \
--data-urlencode 'date=2023-03-29 15:18:25' \
--data-urlencode 'nonce=NQIAO0PNSYHX5DJJVRYUP' \
--data-urlencode 'signType=HMAC-SHA1' \
--data-urlencode 'signature={签名}' \
--data-urlencode 'jobID=898989'
返回示例
{
"code": 1,
"msg": "SUCCESS",
"data": {
"jobID": "909999",
"covers": ["https://test.com/v1.png"],
"video": "https://test.com/v2.mp4?sign=8999"
},
"requestID": "2C1CBC94-9CB1-4EAF-8651-B44314EE9CFF"
}
五、错误码
详见 错误码
六、签名机制
七、回调机制
尽可能提高通知的成功率,但不保证通知最终能成功(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m
)。有可能通知重复,使用方需要幂等设计。回调三方成功定义:返回 http status code
为200
,响应 code
为1
,否则会按照 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h
通知。
请求方法
http
协议 POST
方法
请求参数
Headers 头:
参数名称 | 参数值 | 是否必须 | 示例值 | 说明 |
---|---|---|---|---|
Content-Type |
application/x-www-form-urlencoded | 是 |
请求Body:
参数名称 | 类型 | 是否必填 | 示例值 | 说明 |
---|---|---|---|---|
appID |
string | 是 | 498988 | 应用id |
date |
string | 是 | 2022-7-11 11:15:14 | 日期格式,格式为 2022-7-11 11:15:14 |
nonce |
string | 是 | NQIAO0PNSYHX5DJJVRYUP | 随机字符串 唯一随机数,用于防止网络重放攻击。 |
signType |
string | 是 | HMAC-SHA1 | 签名方法,目前只支持:HMAC-SHA1 |
signature |
string | 是 | YOFzCfDKDTWJSDdAHSzLper+66g= | 签名值,签名方法见签名机制 |
channel |
string | 是 | channel | 渠道 |
jobID |
string | 是 | NQIAO0PNSYHX5DJJVRYUP | 作业id,查询合成作业信息使用 |
data |
string | 是 | 合成作业结果 | json 字符串,具体见:回调数据表(3) |
回调数据表(3)
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
covers |
[]string | 否 | 封面图 url 地址,默认第一个是封面图 | |
video |
string | 是 | 视频 url 地址,有效期为 6 个小时,需要在及时同步走视频。 | |
state |
int | 1 : 作业待运行 2: 作业运行中 3: 作业运行成功 4: 作业运行失败 |
||
ext |
string | 否 | 透传内容,提交接口中ext 字段内容 |
返回参数
名称 | 类型 | 是否必须 | 默认值 | 说明 |
---|---|---|---|---|
code |
int | 是 | 1 为成功,非 1 为失败,具体错误码见响应码 | |
msg |
string | 是 |