公共 API 文档

基础 URL 均为：

/api/v1.php

POST 上传图片

请求体使用 multipart/form-data，文件字段名为 image。详见下文「请求参数」。

GET 查询单张图片公开元数据

查询字符串参数 q：填写数字图片 ID或上传时的完整文件名（精确匹配）。响应格式见「图片元数据查询」一节。

GET /api/v1.php?q=图片ID或完整文件名

隐私：响应中不会返回上传者原始 IP，仅返回打码后的展示串（如 IPv4 为首段与末段可见）；归属地由服务端根据原始 IP 推算，调用方无法据此还原完整 IP。

限流：GET 与 POST 使用不同限流桶；GET 为短窗口 5 秒 / 5 次、长窗口 60 秒 / 120 次（与上传相同数值，互不占用上传配额）。超额返回 429。

成功响应示例：

{
  "success": true,
  "data": {
    "id": 12345,
    "filename": "6640c49c7161b_1715519644.webp",
    "original_filename": "screenshot.png",
    "original_size_bytes": 102400,
    "compressed_size_bytes": 20480,
    "size_display": "100 KB → 20 KB",
    "current_hash": "5317363b47c0d13925879da847c47f09da52ddf28fe7a016819c14b2732862b8",
    "upload_date": "2026-04-30 17:53:59",
    "last_accessed": "2026-04-30 18:15:06",
    "uploader_masked": "202.*.*.165",
    "location": "中国 山东 济南市",
    "tags": "男生、文本",
    "tags_array": ["男生", "文本"],
    "image_url": "https://cdn.example.com/i/6640c49c7161b_1715519644.webp",
    "cdn_domain": "cdn.example.com",
    "password_protected": false
  }
}

last_accessed 若从未记录则为 JSON null。image_url 为可直接用于 <img src> 或过浏览器打开的外链（与上传 API 返回规则一致，不含管理员免密参数）。cdn_domain 为该 URL 的主机名。password_protected 为 true 时表示加密图路径为 /p/，直连可能返回鉴权页而非图片二进制。

失败响应示例（未找到）：

{
  "success": false,
  "error": "未找到与所给条件匹配的图片。",
  "message": "未找到与所给条件匹配的图片。"
}

HTTP 状态码为 404。

本站前端「查询图片信息」弹窗与第三方调用相同，均使用 GET /api/v1.php?q=。

以下字段仅用于 POST multipart/form-data 上传。

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

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

所有响应字段说明：success 标识成败；成功响应中 url 和 data.url 都会返回可访问的图片链接， data 对象还包含文件名和压缩统计；失败响应同时包含 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",
    "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",
    "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": "图片已存在，秒传成功！"
  }
}

失败响应示例：

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

秒传（去重）机制

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

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

秒传命中时响应的 message 字段为 "图片已存在，秒传成功！"，调用方可据此展示提示或统计。

加密上传的安全约束

• 加密上传永远不会被秒传：每一次带 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=@/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

// 查询元数据（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);
?>