跳至主要內容

大约 12 分钟约 3461 字

视频教程

A BiliBili video

秘钥获取

首次使用我们先到个人中心哪里生成一个开放平台秘钥，点击刷新按钮就可以生成了，请注意妥善保管，避免泄漏。如果泄漏可以点击重新生成

SDK接入

如果你用的是下面这些语言，可以忽略下面的内容,直接使用SDK来快速调用

接口说明

开放平台服务基本地址： https://api.zyjj.cc/api/v1/open

秘钥需要在请求头中提交，header头为Authorization，值为 Bearer sk-xxx

比如我们获取一下账户还剩多少可以这样请求

返回如下

{
    "code": 0,
    "data": 966,
    "msg": "ok"
}
  • code 是状态码，0表示成功，其他的为失败，更多状态码可以参考 常用状态码
  • data 是返回的数据，这里返回的是剩余积分
  • msg 是返回的提示信息，如果错误这里会返回错误信息

常用状态码

状态码描述
0成功
10远程服务错误
100积分不足
400参数非法
403秘钥错误
-1未知错误

文件上传

如果有涉及到文件的任务都需要先上传一下文件，获取文件信息后才能创建任务。注意：上传的文件有效期只有7天，过期后会自动删除，请及时使用!

文件上传需要直接和文件服务交互，可以先调用api接口获取文件上传地址，然后直接上传到文件服务即可

直接上传

直接上传支持上传1G以内的文件，实际建议超过100M就使用分片上传。注意：需要调用文件上传接口并且文件服务返回的状态码为200才算完成文件上传操作

  • 接口地址：https://api.zyjj.cc/api/v1/open/file
  • 请求方式：POST
  • 请求体类型：application/json
  • 请求参数：
参数名类型必填描述
file_namestring是文件名称
file_sizeint是文件大小

  • 返回参数：

    • auth：认证信息(有效期1个小时，请尽快使用)
      • url： 文件服务url
      • header：文件上传请求头
    • file：文件信息（需要调用文件服务上传成功后才能使用）

  • 返回示例：

{
  "code": 0,
  "data": {
    "auth": {
      "url": "https://zyjj-1252481943.cos.ap-shanghai.myqcloud.com/tmp/65b1aa96d633cb4aefb7871e/50d80f2baf1d4c19a90cd7252573372b.txt",
      "header": {
        "Content-Length": "10",
        "Host": "zyjj-1252481943.cos.ap-shanghai.myqcloud.com",
        "Authorization": "q-sign-algorithm=sha1&q-ak=AKIDwlR2Vp6A5qPluwmrjNp37ya0NZXKzWwA&q-sign-time=1734915165;1734925965&q-key-time=1734915165;1734925965&q-header-list=&q-url-param-list=&q-signature=d34c5ce10d8cd108177fe5a6b6997e9722295872",
        "Content-Type": "application/octet-stream"
      }
    },
    "file": {
      "name": "1.txt",
      "path": "tmp/65b1aa96d633cb4aefb7871e/50d80f2baf1d4c19a90cd7252573372b.txt",
      "source": 1,
      "size": 10
    }
  },
  "msg": "ok"
}

获取到auth信息后，我们需要给这个文件服务上传文件，body为文件内容的二进制信息，header直接使用auth里面的header即可，不需要传其他内容

  • 代码示例
python
base = "https://api.zyjj.cc/api/v1"
# 下面这个替换为自己的秘钥
sk = "sk-xxx"
# 直接上传
with open("tmp.jpg", "rb") as f:
    file_data = f.read()
    # 获取上传的鉴权信息
    data = requests.post(
        f"{base}/open/file",
        json={"file_name": "tmp.jpg", "file_size": len(file_data)},
        headers={"Authorization": sk}
    ).json()
    # 检查返回值是否正确
    if data["code"] != 0:
        raise Exception(data["msg"])
    data = data["data"]
    # 认证信息
    auth = data["auth"]
    # 通过认证信息里面的url和header来上传文件
    res = requests.put(
        auth["url"],
        data=file_data,
        headers=auth["header"]
    )
    # 需要确保上传完成
    res.raise_for_status()
    # 打印我们最后的文件信息
    print(data["file"])

分片上传

分片上传支持乱序和并发上传，主要分为3步，第一步是初始化分片上传获取上传id，然后通过上传id上传分片文件，最后调用完成接口完成整个流程

1.初始化分片上传

  • 接口地址：https://api.zyjj.cc/api/v1/open/file/multipart/init
  • 请求方式：POST
  • 请求体类型：application/json
  • 请求参数：
参数名类型必填描述
file_namestring是文件名称
file_sizeint是文件大小

  • 返回参数： 上传id

  • 返回示例：

{
  "code": 0,
  "data": "1734915962b9f73fe5ccc4e6c846e5a13c58301973ab363de3cdfe515bc9711446436773ae",
  "msg": "ok"
}

2.上传分片文件

通过第一步分片上传初始化后我们获取到了一个上传id，下面我们可以根据实际需求把一个大文件拆成多个分片，然后调用该接口获取一下上传信息，最后通过文件服务来上传这个分片

  • 接口地址：https://api.zyjj.cc/api/v1/open/file/multipart/part
  • 请求方式：POST
  • 请求体类型：application/json
  • 请求参数：
参数名类型必填描述
upload_idstring是上传id
part_numint是当前第几个分片（注意必须大于0）

  • 返回参数：

    • url：文件服务url
    • header：文件上传请求头

  • 返回示例：

{
  "code": 0,
  "data": {
    "url": "https://zyjj-1252481943.cos.ap-shanghai.myqcloud.com/tmp/65b1aa96d633cb4aefb7871e/8c58bb04a42d4751bf551595b7220862.txt?partNumber=1&uploadId=1734915962b9f73fe5ccc4e6c846e5a13c58301973ab363de3cdfe515bc9711446436773ae",
    "header": {
      "Authorization": "q-sign-algorithm=sha1&q-ak=AKIDwlR2Vp6A5qPluwmrjNp37ya0NZXKzWwA&q-sign-time=1734916291;1734927091&q-key-time=1734916291;1734927091&q-header-list=&q-url-param-list=partNumber;uploadId&q-signature=2371a0cfdccf50b35ba482661acd18adf89964e1"
    }
  },
  "msg": "ok"
}

调用文件服务完成上传后需要获取一下文件服务返回的header里面的ETag字段，后续完成分片上传接口需要改字段

3.完成分片上传

当我们上传完所有的分片后，需要调用该接口完成分片上传，该接口会直接返回上传好的文件信息

  • 接口地址：https://api.zyjj.cc/api/v1/open/file/multipart/complete
  • 请求方式：POST
  • 请求体类型：application/json
  • 请求参数：
参数名类型必填描述
upload_idstring是上传id
part_listarray是分片列表
part_list.part_numint是分片序号
part_list.etagstring是文件服务返回的etag信息
  • 返回参数：文件信息
  • 请求示例
{
  "upload_id": "1734915962b9f73fe5ccc4e6c846e5a13c58301973ab363de3cdfe515bc9711446436773ae",
  "part_list": [{"part_num": 1, "etag": "\"4a1ee502a19674fa24ed1c75dff62288\""}, {"part_num": 2, "etag": "\"8dfcde7ccc361d4e876122ef9fd780cb\""}]
}
  • 返回示例：
{
    "code": 0,
    "data": {
        "name": "test.mp4",
        "path": "tmp/65b1aa96d633cb4aefb7871e/626558ad176043de83b40f47e2abf1dc.mp4",
        "source": 1
    },
    "msg": "ok"
}

代码示例

python
base = "https://api.zyjj.cc/api/v1"
# 替换为自己的sk
sk = "sk-xxx"
# 文件所在路径
path = "test.mp4"
# 先初始化分片上传获取上传id
file_size = os.path.getsize(path)
data = requests.post(
    f"{base}/open/file/multipart/init",
    json={"file_name": path.split("/")[0], "file_size": file_size},
    headers={"Authorization": sk}
).json()
if data["code"] != 0:
    raise Exception(data["msg"])
# 获取upload_id
upload_id = data["data"]
# 这里写自己的分片上传逻辑
with open(path, "rb") as f:
    part_list = []
    # 我们每次分片大小为1M
    chunk_size = 1024 * 1024
    # part_num 需要从1开始
    part_num = 1
    while True:
        part_data = f.read(chunk_size)  # 读取指定大小的块
        if not part_data:  # 如果没有更多数据，退出循环
            break
        # 获取鉴权信息
        data = requests.post(
            f"{base}/open/file/multipart/part",
            json={"upload_id": upload_id, "part_num": part_num},
            headers={"Authorization": sk}
        ).json()
        if data["code"] != 0:
            raise Exception(data["msg"])
        data = data["data"]
        # 调用文件服务上传我们的实际文件
        res = requests.put(
            data["url"],
            data=part_data,
            headers=data["header"]
        )
        print(data["header"])
        print(res.text)
        res.raise_for_status()
        # 从返回的header中获取etag信息
        part_list.append({"part_num": part_num, "etag": res.headers.get("etag")})
        part_num += 1
    # 最后我们完成上传
    data = requests.post(
        f"{base}/open/file/multipart/complete",
        json={"upload_id": upload_id, "part_list": part_list},
        headers={"Authorization": sk}
    ).json()
    if data["code"] != 0:
        raise Exception(data["msg"])
    # 直接打印最后的文件信息
    print(data["data"])

小文件快速上传（不推荐）

可以直接调用openapi接口上传小于10M的文件并自动返回文件信息，这个方法最简单，但是上传速度很慢，仅适合测试使用

  • 接口地址：https://api.zyjj.cc/api/v1/open/file/simple
  • 请求方式：POST
  • 请求体类型：multipart/form-data
  • 请求参数：
参数名类型必填描述
filefile是文件信息

  • 返回参数：

    • name：文件名
    • path：文件路径
    • source：文件来源，默认为1
    • size：文件大小

  • 返回示例：

{
    "code": 0,
    "data": {
        "name": "Pasted image 20240321225952.png",
        "path": "tmp/65b1aa96d633cb4aefb7871e/513cbd3dc85748028d9ce279a4915b60.png",
        "source": 1,
        "size": 1399184
    },
    "msg": "ok"
}
  • postman示例

同步任务创建

同步任务适用于耗时比较短的任务，比如语音合成、文本生成、人脸年龄变化等任务，直接请求即可直接返回结果，部分任务可能无法使用同步方式，可以参考下面的异步任务创建

  • 接口地址：https://api.zyjj.cc/api/v1/open/task/async
  • 请求方式：POST
  • 请求体类型：application/json
  • 请求参数：
参数名类型必填描述
task_typeint是任务类型
inputobject是任务输入参数
  • 返回参数： 直接返回任务的内容
  • 返回示例：
{
  "code": 0,
  "data": {
    "text": "你好，世界"
  },
  "msg": "ok"
}
  • postman示例

异步任务创建 (推荐)

同步创建如果中途请求中断会导致任务丢失，所以推荐使用异步创建，异步创建会返回一个任务id，可以通过任务id查询任务的状态和结果，所有任务都支持异步创建的方式

  • 接口地址：https://api.zyjj.cc/api/v1/open/task
  • 请求方式：POST
  • 请求体类型：application/json
  • 请求参数：
参数名类型必填描述
task_typeint是任务类型
inputobject是任务输入参数
  • 返回参数：任务id
  • 返回示例：
{
  "code": 0,
  "data": "675b00e82168f3401c530d03",
  "msg": "ok"
}
  • postman示例

任务状态查询

经过前面异步任务创建后会返回一个任务id，可以通过任务id查询任务的状态和结果

  • 接口地址：https://api.zyjj.cc/api/v1/open/task/{task_id}
  • 请求方式：GET
  • 请求体类型：application/json
  • 请求参数：路径参数，需要把task_id放到请求地址中
  • 返回参数：
    • status：任务状态（0创建 1进行 2成功 3失败 4取消）
    • output：任务的输出结果
    • progress：任务的进度，0-100
    • err_code：错误码，0表示成功，其他的为失败，更多错误码可以参考 常用状态码
    • err_msg：错误信息
    • point_cost：本次任务消耗的积分
  • 返回示例：
{
    "code": 0,
    "data": {
        "status": 2,
        "output": {
            "text": "你好，世界"
        },
        "progress": 100.0,
        "err_code": 0,
        "err_msg": "",
        "point_cost": 3
    },
    "msg": "ok"
}
  • postman示例

任务列表

文案

功能名称任务类型接口文档效果示例
文章框架分析1001立即跳转立即跳转
文章打分1001立即跳转立即跳转
文章表达优化1001立即跳转立即跳转
文章翻译1001立即跳转立即跳转
文章总结1001立即跳转立即跳转
文章排版1001立即跳转立即跳转
重点总结1001立即跳转立即跳转
文章改写1001立即跳转立即跳转
文章扩写1001立即跳转立即跳转
小红书标题生成1001立即跳转立即跳转
小红书文案生成1001立即跳转立即跳转
短视频脚本生成1001立即跳转立即跳转
诗歌创作1001立即跳转立即跳转
小说生成1001立即跳转立即跳转
影评生成1001立即跳转立即跳转
段子生成1001立即跳转立即跳转
slogan生成1001立即跳转立即跳转
科幻小说生成1001立即跳转立即跳转
狗血软文生成1001立即跳转立即跳转
雷军演讲生成1001立即跳转立即跳转

字幕

功能名称任务类型接口文档效果示例
字幕识别（多语种）1021立即跳转立即跳转
字幕识别（中英文）1022立即跳转立即跳转
字幕翻译1025立即跳转立即跳转

图片

功能名称任务类型接口文档效果示例
图像增强1005立即跳转立即跳转
文生图(AI绘画)1006立即跳转立即跳转
图生图1007立即跳转立即跳转
人脸年龄变化1008立即跳转立即跳转
人脸性别变化1009立即跳转立即跳转
人脸动漫化1010立即跳转立即跳转
人像抠图1011立即跳转立即跳转
图像消除(图像修复)1032立即跳转立即跳转
证件照生成1033立即跳转立即跳转
漫画翻译1038立即跳转立即跳转
照片上色1039立即跳转立即跳转

音频

功能名称任务类型接口文档效果示例
语音识别1002立即跳转立即跳转
语音合成（微软）1004立即跳转立即跳转
人声伴奏分离1030立即跳转立即跳转

视频

工具

功能名称任务类型接口文档效果示例
B站视频解析1014立即跳转立即跳转
B站封面解析1015立即跳转立即跳转
B站字幕下载1018立即跳转立即跳转
B站弹幕下载1028立即跳转立即跳转
B站视频总结1027立即跳转立即跳转
B站评论词云1029立即跳转立即跳转
ncm转mp31016立即跳转立即跳转
网易云音乐解析1020立即跳转立即跳转
小红书图片下载1019立即跳转立即跳转
词云生成1023立即跳转立即跳转
抖音视频下载1026立即跳转立即跳转
网页内容获取1034立即跳转立即跳转
动漫人脸识别1036立即跳转立即跳转
上次编辑于:
贡献者: xiaoyou