公共 API 文档

您可以在上传时通过 cdn_domain 参数指定以下任意一个域名。如果不指定，系统将自动选择。

API 的响应统一为 JSON 格式，Content-Type: application/json; charset=utf-8。

所有响应字段说明：success 标识成败；成功响应中 url 和 data.url 都会返回可访问的图片链接， data 对象还包含 filename、storage_backend（local / telegram / r2）、压缩统计等； 失败响应同时包含 error 与 message 两个字段（内容一致，便于客户端任选其一读取）。

成功响应示例（公开图片）：

{
  "success": true,
  "url": "https://img.scdn.io/i/6640c49c7161b_1715519644.webp",
  "data": {
    "url": "https://img.scdn.io/i/6640c49c7161b_1715519644.webp",
    "filename": "6640c49c7161b_1715519644.webp",
    "storage_backend": "local",
    "original_size": 102400,
    "compressed_size": 20480,
    "compression_ratio": 80
  }
}

成功响应示例（带密码加密图）：

{
  "success": true,
  "url": "https://img.scdn.io/p/unique_encrypted_id_string.webp",
  "data": {
    "url": "https://img.scdn.io/p/unique_encrypted_id_string.webp",
    "filename": "unique_encrypted_id_string.webp",
    "storage_backend": "local",
    "original_size": 102400,
    "compressed_size": 20480,
    "compression_ratio": 80
  }
}

加密图 URL 以 /p/ 开头，访问时必须提供正确密码。返回的 URL 不会附带任何免密凭证。

秒传成功响应示例：

{
  "success": true,
  "url": "https://img.scdn.io/i/existing_image_name.webp",
  "message": "图片已存在，秒传成功！",
  "data": {
    "url": "https://img.scdn.io/i/existing_image_name.webp",
    "message": "图片已存在，秒传成功！",
    "filename": "existing_image_name.webp",
    "storage_backend": "local"
  }
}

失败响应示例：

{
  "success": false,
  "error":   "请求过于频繁，请稍后再试。",
  "message": "请求过于频繁，请稍后再试。"
}

秒传（去重）机制

服务端以 SHA-256 哈希对上传文件做去重，命中以下任一条件会直接返回已有图片链接，不重复存储：

• 压缩产物命中：上传的文件本身就是此前某张图片压缩后的产物（按压缩后文件的哈希匹配）。
• 原图 + 输出格式命中：此前曾用同一张原图、相同 outputFormat 上传过。

秒传命中时响应的 message 字段为 "图片已存在，秒传成功！"；data.filename 为命中记录的文件名；data.storage_backend 为命中记录的实际存储（local / telegram / r2），调用方可据此展示提示或统计。

加密上传的安全约束

• 加密上传永远不会被秒传：每一次带 password_enabled=true 的上传都会生成新的加密文件，避免命中别人的公共或加密版本导致密码语义失效。
• 无密码上传只会命中公共版本：不会把某张加密图的 /p/ 链接返回给不知道密码的调用方。
• 返回的加密图 URL 不携带任何免密凭证：拿到 URL 的任何一方都必须凭密码访问。

• cURL
• JavaScript
• Python
• PHP

curl -sG --data-urlencode "q=6640c49c7161b_1715519644.webp" "https://img.scdn.io/api/v1.php"

curl -X POST -F "image=@/path/to/your/image.jpg" https://img.scdn.io/api/v1.php

curl -X POST \
-F "image_url=https://example.com/path/to/image.jpg" \
https://img.scdn.io/api/v1.php

curl -X POST \
-F "image=@/path/to/your/animation.gif" \
-F "outputFormat=webp_animated" \
https://img.scdn.io/api/v1.php

curl -X POST \
-F "image=@/path/to/your/image.jpg" \
-F "password_enabled=true" \
-F "image_password=your_secret_password" \
https://img.scdn.io/api/v1.php

curl -X POST \
-F "image=@/path/to/your/image.jpg" \
-F "password_enabled=true" \
-F "password_type=qa" \
-F "password_question=我养的第一只宠物叫什么？" \
-F "image_password=Tom" \
https://img.scdn.io/api/v1.php

curl -X POST \
-F "image=@/path/to/your/image.jpg" \
-F "cdn_domain=img.scdn.io" \
https://img.scdn.io/api/v1.php

curl -X POST \
-F "image=@/path/to/your/image.jpg" \
-F "storage_destination=telegram" \
https://img.scdn.io/api/v1.php

curl -X POST \
-F "image=@/path/to/your/image.jpg" \
-F "storage_destination=r2" \
https://img.scdn.io/api/v1.php

// 查询元数据（GET）
fetch('https://img.scdn.io/api/v1.php?q=' + encodeURIComponent('6640c49c7161b_1715519644.webp'))
  .then(r => r.json())
  .then(data => console.log(data));

// 上传（POST）
const fileInput = document.querySelector('input[type="file"]');
const formData = new FormData();
formData.append('image', fileInput.files[0]);
formData.append('cdn_domain', 'img.scdn.io');

fetch('https://img.scdn.io/api/v1.php', {
  method: 'POST',
  body: formData
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

import requests

# 查询元数据
r = requests.get('https://img.scdn.io/api/v1.php', params={'q': '6640c49c7161b_1715519644.webp'})
print(r.json())

# 上传
url = 'https://img.scdn.io/api/v1.php'
file_path = '/path/to/your/image.jpg'

with open(file_path, 'rb') as f:
    files = {'image': f}
    # 指定CDN域名 (可选)
    data = {'cdn_domain': 'img.scdn.io'}
    response = requests.post(url, files=files, data=data)

print(response.json())

<?php
$base = 'https://img.scdn.io/api/v1.php';

// 查询元数据（GET）
$q = '6640c49c7161b_1715519644.webp';
echo file_get_contents($base . '?q=' . rawurlencode($q));

// 上传（POST）
$filePath = '/path/to/your/image.jpg';

if (!file_exists($filePath)) {
    die('错误: 文件不存在。');
}

$cfile = new CURLFile($filePath, mime_content_type($filePath), basename($filePath));

$postData = [
    'image' => $cfile,
    'cdn_domain' => 'img.scdn.io',
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $base);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL 错误: ' . curl_error($ch);
} else {
    header('Content-Type: application/json');
    echo $response;
}

curl_close($ch);
?>