首页文档控制台定价

Python 签名 SDK 接入指南

功能说明

Python 签名 SDK 使用 AK/SK 为美图开放平台 API 请求生成 Authorization 和 X-Sdk-Date 请求头，并返回可直接发送的 requests.PreparedRequest。SDK 负责请求签名，业务请求字段和响应结构以对应 API 文档为准。

环境要求

  • Python 3.6 或更高版本
  • requests 库
  • 可通过 HTTPS 访问 openapi.meitu.com

下载与引入

当前版本：AIGCP-API-python-sdk-1.0.3

下载 Python SDK 1.0.3

解压后的主要文件：

AIGCP-API-python-sdk-1.0.3/
├── demo.py
└── sign_sdk/
    ├── __init__.py
    └── sign.py

将整个 sign_sdk 目录复制到项目中，并安装依赖：

python3 -m pip install requests

代码中按以下方式引入：from sign_sdk import sign。

接口说明

创建签名器

sign.Signer(access_key, secret_key)

参数类型说明
access_keystr开放平台 AK
secret_keystr开放平台 SK

签名请求

signer.sign(url, method, headers, body)

参数类型说明
urlstr完整请求 URL，包含路径和查询参数
methodstr大写 HTTP 方法，例如 GET、POST
headersdict待签名请求头，必须包含与 URL 一致的 Host
bodystr最终请求体；无请求体时传空字符串 ""
返回值requests.PreparedRequest可交给 requests.Session.send() 直接发送的请求

未提供 X-Sdk-Date 时，SDK 会自动写入当前 UTC 时间。SDK 还会将 Authorization 写入传入的 headers 字典。

Python SDK 1.0.1 及以上支持请求头 X-Sdk-Content-Sha256: UNSIGNED-PAYLOAD。设置后，规范请求的 body 哈希位置使用字面值 UNSIGNED-PAYLOAD，请求体仍会正常发送。

POST 完整调用示例

以下示例调用正式任务提交接口。请求体包含 task、task_type、init_images、params、sync_timeout 五个顶层字段，其中 params 必须是 JSON 字符串。请将任务名称、任务类型、图片、算法参数和超时时间替换为目标 API 文档规定的值。

import json

import requests
from sign_sdk import sign

ACCESS_KEY = "YOUR_ACCESS_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
URL = "https://openapi.meitu.com/api/v1/sdk/sync/push"

params = {
    "parameter": {
        "rsp_media_type": "url",
    }
}
payload = {
    "task": "/v1/replace-with-product-task",
    "task_type": "formula",
    "init_images": [
        {
            "url": "https://example.com/input.jpg",
            "profile": {
                "media_profiles": {
                    "media_data_type": "url",
                },
                "version": "v1",
            },
        }
    ],
    "params": json.dumps(
        params,
        ensure_ascii=True,
        separators=(",", ":"),
    ),
    "sync_timeout": 30,
}
body = json.dumps(
    payload,
    ensure_ascii=True,
    separators=(",", ":"),
)
headers = {
    "Content-Type": "application/json",
    sign.HeaderHost: "openapi.meitu.com",
}

signer = sign.Signer(ACCESS_KEY, SECRET_KEY)
signed_request = signer.sign(URL, "POST", headers, body)

with requests.Session() as session:
    response = session.send(
        signed_request,
        timeout=(5, 30),
        verify=True,
    )
    response.raise_for_status()
    print(response.json())

GET 调用示例

以下示例查询任务状态。将 YOUR_TASK_ID 替换为任务提交接口返回的任务 ID。

import requests
from sign_sdk import sign

ACCESS_KEY = "YOUR_ACCESS_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
URL = (
    "https://openapi.meitu.com/api/v1/sdk/status"
    "?task_id=YOUR_TASK_ID"
)
headers = {
    sign.HeaderHost: "openapi.meitu.com",
}

signer = sign.Signer(ACCESS_KEY, SECRET_KEY)
signed_request = signer.sign(URL, "GET", headers, "")

with requests.Session() as session:
    response = session.send(
        signed_request,
        timeout=(5, 30),
        verify=True,
    )
    response.raise_for_status()
    print(response.json())

注意事项

  • Host 必须与 URL 中的主机一致，本平台为 openapi.meitu.com。
  • HTTP 方法必须使用大写；URL、查询参数、已签名请求头和 body 在签名后不能修改。
  • params 是 JSON 字符串，不是 JSON 对象；应先序列化 params，再序列化外层请求体。
  • body 必须是字符串。同一份字符串同时用于签名和发送，不要在签名后再次序列化。
  • 每次请求创建新的 headers 字典，避免复用 SDK 已写入 Authorization 的旧字典。
  • 保持服务器时钟同步，并为请求设置连接和读取超时。
  • 正式请求使用 HTTPS 并保持证书校验；SK 只能保存在服务端。

常见错误

错误现象处理方法
401 或验签失败检查 AK/SK、HTTP 方法、Host、URL、查询参数、请求头和 body 是否与签名时完全一致。
第二次请求验签失败不要复用上一次签名使用的 headers 字典，每次创建新字典。
AttributeError: ... encodebody 不是字符串；先使用 json.dumps() 序列化，无请求体时传 ""。
请求时间错误同步服务器时钟，不要传入过期或格式错误的 X-Sdk-Date。
请求超时检查网络连通性和接口处理时间，并按业务场景调整 timeout。
TLS 证书错误检查域名、系统时间和证书链，保持 verify=True。
HTTP 成功但业务失败继续检查响应 JSON 中的业务状态码和错误信息。