• API 功能

    • 支持本地上传图片或网络图片 URL,一键完成压缩;
    • 自动保持图片长宽比,可按目标尺寸或最大尺寸进行等比缩放;
    • 针对 JPEG 采用优化压缩(渐进式、优化 Huffman 表等),在保证清晰度的前提下显著减小体积;
    • 支持 PNG 等无损格式的体积优化压缩;
    • 自动限制过大图片的尺寸(默认 1920 像素上限),避免带宽浪费;
    • 全接口支持 HTTPS(TLS v1.0 / v1.1 / v1.2 / v1.3),全面兼容 Apple ATS;
    • 全国多节点 CDN 部署,接口极速响应;
    • 接口调用状态与状态监控
  • API 文档

    接口地址: https://api.gugudata.com/ai/image-compress

    返回格式: application/json; charset=utf-8

    请求方式: POST

    请求协议: HTTPS

    请求示例: https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY

    数据预览: https://www.gugudata.com/preview/image-compress

    接口测试:  https://api.gugudata.com/ai/image-compress/demo

    OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json

    请求参数(POST 请求参数以 application/x-www-form-urlencoded 格式、文件流以 formdata 格式传递,具体可参见下方示例代码)

    参数名 参数类型 是否必须 默认值 备注
    appkey string YOUR_APPKEY 付费后获取的 APPKEY,可通过 Query 参数或 Form 字段 appkey 传递
    image_file string/binary 上传的图片文件,支持 JPG / JPEG / PNG / GIF / WEBP / BMP,与 image_url 二选一必填
    image_url string 网络图片 URL,与 image_file 二选一必填,需为可直接访问的 HTTP/HTTPS 链接
    targetwidth integer 目标宽度(像素),与 targetHeight 组合使用时按照最长边等比缩放;不传则不以此为约束
    targetheight integer 目标高度(像素),与 targetWidth 组合使用时按照最长边等比缩放;不传则不以此为约束
    maxwidth integer 最大宽度(像素),只限制不超过该宽度并保持长宽比;当未显式传递任何尺寸参数且图片特别大时,服务会自动使用 1920 作为默认上限
    maxheight integer 最大高度(像素),只限制不超过该高度并保持长宽比;当未显式传递任何尺寸参数且图片特别大时,服务会自动使用 1920 作为默认上限
    quality integer 85 JPEG 压缩质量,取值范围 1-95,数值越低压缩越厉害,推荐在 60-90 之间;PNG 等无损格式将使用内部优化策略忽略该参数
    format string 输出图片格式,可选值:jpeg、png 等;不传则保持原图格式(对于部分不常见格式会自动转换为 JPEG)

    返回参数

    参数名 参数类型 备注
    HTTP Header.Content-Type string 返回图片的 MIME 类型,例如 image/jpeg、image/png 等
    HTTP Header.Content-Disposition string 文件下载头,包含建议的下载文件名,默认会根据原始文件名和格式自动生成
    Body(Binary) string/binary 压缩后图片的二进制流内容,可直接保存为图片文件或在浏览器中显示
  • 接口 HTTP 响应标准状态码

    状态码 状态码解释 备注
    200 接口正常响应 请求成功,业务状态请结合响应体中的自定义业务码判断。
    400 请求参数错误 请求参数缺失、格式错误或参数组合不合法。
    401 鉴权失败 缺少 appkey 或 appkey 无效。
    403 无权限访问 订单到期、权限不足或接口额度不可用。
    404 资源不存在 请求路径不存在。
    405 请求方法不允许 当前路径不支持该 HTTP 方法。
    415 请求内容类型不支持 上传或请求体的内容类型不符合接口要求。
    429 请求频率受限 一般建议同一个 IP 每秒请求不超过 5 次 (QPS<=5),我们不限制同一个 key 的请求总次数,但当单位时间内同一个 IP 请求次数过多,或 AI CDN 判定为恶意抓取数据、流量攻击等异常时,CDN 会返回此状态码,请适当降低请求频率。如有特殊大并发请求场景需求,可联系我们添加白名单处理。
    500 服务内部错误 服务端处理异常,请稍后重试。
    502 上游依赖错误 上游依赖服务不可用或返回异常。
  • 接口自定义状态码

    自定义状态码 自定义状态码解释 备注
    100 正常返回
    101 参数错误 appkey 缺失,image_file 与 image_url 均为空,或 quality/尺寸参数不合法
    102 请求频率受限 每秒请求不能超过平台限制
    103 账号欠费
    104 APPKEY 错误 请检查传递的 APPKEY 是否为开发者中心获取到的值
    110 图片格式不支持或文件损坏 Pillow 无法识别图片,或图片超过最大限制(当前为 10MB)
    111 图片下载失败 当通过 image_url 下载图片失败或超时时返回
    112 服务内部错误 压缩过程中发生未预期异常
  • 请求示例代码
    curl --location 'https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY' \
    --form 'image_url=' \
    --form 'targetWidth=' \
    --form 'targetHeight=' \
    --form 'maxWidth=' \
    --form 'maxHeight=' \
    --form 'quality=85' \
    --form 'format=' \
    --form 'image_file=@localfile_path.png'
    #include <curl/curl.h>
    
    int main(void) {
      CURL *curl = curl_easy_init();
      if (curl) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY");
        curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
        curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
        curl_mime *mime = curl_mime_init(curl);
        curl_mimepart *part = NULL;
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "image_url");
        curl_mime_data(part, "", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "targetWidth");
        curl_mime_data(part, "", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "targetHeight");
        curl_mime_data(part, "", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "maxWidth");
        curl_mime_data(part, "", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "maxHeight");
        curl_mime_data(part, "", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "quality");
        curl_mime_data(part, "85", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "format");
        curl_mime_data(part, "", CURL_ZERO_TERMINATED);
        part = curl_mime_addpart(mime);
        curl_mime_name(part, "image_file");
        curl_mime_filedata(part, "localfile_path.png");
        curl_easy_setopt(curl, CURLOPT_MIMEPOST, mime);
        CURLcode res = curl_easy_perform(curl);
        (void)res;
        curl_mime_free(mime);
        curl_easy_cleanup(curl);
      }
      return 0;
    }
    
    using System;
    using System.Collections.Generic;
    using System.IO;
    using System.Net.Http;
    
    var client = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Post, "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY");
    var content = new MultipartFormDataContent();
    content.Add(new StringContent(""), "image_url");
    content.Add(new StringContent(""), "targetWidth");
    content.Add(new StringContent(""), "targetHeight");
    content.Add(new StringContent(""), "maxWidth");
    content.Add(new StringContent(""), "maxHeight");
    content.Add(new StringContent("85"), "quality");
    content.Add(new StringContent(""), "format");
    content.Add(new StreamContent(File.OpenRead("localfile_path.png")), "image_file", "localfile_path.png");
    request.Content = content;
    var response = client.SendAsync(request).Result;
    Console.WriteLine(response.Content.ReadAsStringAsync().Result);
    
    package main
    
    import (
      "bytes"
      "mime/multipart"
      "os"
      "path/filepath"
      "fmt"
      "io"
      "net/http"
    )
    
    func main() {
      url := "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY"
      payload := &bytes.Buffer{}
      writer := multipart.NewWriter(payload)
      _ = writer.WriteField("image_url", "")
      _ = writer.WriteField("targetWidth", "")
      _ = writer.WriteField("targetHeight", "")
      _ = writer.WriteField("maxWidth", "")
      _ = writer.WriteField("maxHeight", "")
      _ = writer.WriteField("quality", "85")
      _ = writer.WriteField("format", "")
      file, err := os.Open("localfile_path.png")
      if err != nil {
        fmt.Println(err)
        return
      }
      defer file.Close()
      part, err := writer.CreateFormFile("image_file", filepath.Base("localfile_path.png"))
      if err != nil {
        fmt.Println(err)
        return
      }
      if _, err = io.Copy(part, file); err != nil {
        fmt.Println(err)
        return
      }
      if err := writer.Close(); err != nil {
        fmt.Println(err)
        return
      }
      req, err := http.NewRequest("POST", url, payload)
      if err != nil {
        fmt.Println(err)
        return
      }
      req.Header.Set("Content-Type", writer.FormDataContentType())
      res, err := http.DefaultClient.Do(req)
      if err != nil {
        fmt.Println(err)
        return
      }
      defer res.Body.Close()
      body, err := io.ReadAll(res.Body)
      if err != nil {
        fmt.Println(err)
        return
      }
      fmt.Println(string(body))
    }
    
    OkHttpClient client = new OkHttpClient().newBuilder().build();
    RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
      .addFormDataPart("image_url", "")
      .addFormDataPart("targetWidth", "")
      .addFormDataPart("targetHeight", "")
      .addFormDataPart("maxWidth", "")
      .addFormDataPart("maxHeight", "")
      .addFormDataPart("quality", "85")
      .addFormDataPart("format", "")
      .addFormDataPart("image_file", "localfile_path.png",
        RequestBody.create(MediaType.parse("application/octet-stream"), new File("localfile_path.png")))
      .build();
    Request request = new Request.Builder()
      .url("https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY")
      .method("POST", body)
      .build();
    Response response = client.newCall(request).execute();
    System.out.println(response.body().string());
    
    var form = new FormData();
    form.append("image_url", "");
    form.append("targetWidth", "");
    form.append("targetHeight", "");
    form.append("maxWidth", "");
    form.append("maxHeight", "");
    form.append("quality", "85");
    form.append("format", "");
    form.append("image_file", fileInput.files[0], "localfile_path.png");
    
    $.ajax({
      url: "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY",
      method: "POST",
      data: form,
      processData: false,
      contentType: false
    }).done(function (response) {
      console.log(response);
    });
    
    const formData = new FormData();
    formData.append("image_url", "");
    formData.append("targetWidth", "");
    formData.append("targetHeight", "");
    formData.append("maxWidth", "");
    formData.append("maxHeight", "");
    formData.append("quality", "85");
    formData.append("format", "");
    formData.append("image_file", fileInput.files[0], "localfile_path.png");
    
    const response = await fetch("https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY", {
      method: "POST",
      body: formData
    });
    console.log(await response.text());
    
    import { readFile } from "node:fs/promises";
    
    const formData = new FormData();
    formData.append("image_url", "");
    formData.append("targetWidth", "");
    formData.append("targetHeight", "");
    formData.append("maxWidth", "");
    formData.append("maxHeight", "");
    formData.append("quality", "85");
    formData.append("format", "");
    formData.append("image_file", new Blob([await readFile("localfile_path.png")], { type: "application/octet-stream" }), "localfile_path.png");
    
    const response = await fetch("https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY", {
      method: "POST",
      body: formData
    });
    console.log(await response.text());
    
    #import <Foundation/Foundation.h>
    
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY"]];
    [request setHTTPMethod:@"POST"];
    NSString *boundary = [[NSUUID UUID] UUIDString];
    NSMutableData *body = [NSMutableData data];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"image_url\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"targetWidth\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"targetHeight\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"maxWidth\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"maxHeight\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"quality\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"85\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"format\"\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    NSData *image_fileData = [NSData dataWithContentsOfFile:@"localfile_path.png"];
    [body appendData:[[NSString stringWithFormat:@"--%@\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Disposition: form-data; name=\"image_file\"; filename=\"localfile_path.png\"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[@"Content-Type: application/octet-stream\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:image_fileData];
    [body appendData:[@"\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
    [body appendData:[[NSString stringWithFormat:@"--%@--\r\n", boundary] dataUsingEncoding:NSUTF8StringEncoding]];
    [request setValue:[NSString stringWithFormat:@"multipart/form-data; boundary=%@", boundary] forHTTPHeaderField:@"Content-Type"];
    [request setHTTPBody:body];
    NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
      if (error) {
        NSLog(@"%@", error);
        return;
      }
      NSLog(@"%@", [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]);
    }];
    [task resume];
    
    <?php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS => array(
        "image_url" => "",
        "targetWidth" => "",
        "targetHeight" => "",
        "maxWidth" => "",
        "maxHeight" => "",
        "quality" => "85",
        "format" => "",
        "image_file" => new CURLFile("localfile_path.png", "application/octet-stream", "localfile_path.png"),
      ),
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
    
    import requests
    
    url = "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY"
    payload = { "image_url": "", "targetWidth": "", "targetHeight": "", "maxWidth": "", "maxHeight": "", "quality": "85", "format": "" }
    files = {
        "image_file": ("localfile_path.png", open("localfile_path.png", "rb"), "application/octet-stream"),
    }
    try:
        response = requests.post(url, data=payload, files=files)
        print(response.text)
    finally:
        for _, file_handle, _ in files.values():
            file_handle.close()
    
    require "uri"
    require "net/http"
    
    url = URI("https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY")
    https = Net::HTTP.new(url.host, url.port)
    https.use_ssl = true
    request = Net::HTTP::Post.new(url)
    files = [
      File.open("localfile_path.png"),
    ]
    begin
      form_data = [
        ["image_url", ""],
        ["targetWidth", ""],
        ["targetHeight", ""],
        ["maxWidth", ""],
        ["maxHeight", ""],
        ["quality", "85"],
        ["format", ""],
        ["image_file", files[0], { filename: "localfile_path.png" }],
      ]
      request.set_form form_data, "multipart/form-data"
      response = https.request(request)
      puts response.read_body
    ensure
      files.each(&:close)
    end
    
    import Foundation
    
    let semaphore = DispatchSemaphore(value: 0)
    var request = URLRequest(url: URL(string: "https://api.gugudata.com/ai/image-compress?appkey=YOUR_APPKEY")!, timeoutInterval: .infinity)
    request.httpMethod = "POST"
    let boundary = "Boundary-\(UUID().uuidString)"
    var body = Data()
    func appendString(_ value: String) { body.append(value.data(using: .utf8)!) }
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"image_url\"\r\n\r\n")
    appendString("\r\n")
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"targetWidth\"\r\n\r\n")
    appendString("\r\n")
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"targetHeight\"\r\n\r\n")
    appendString("\r\n")
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"maxWidth\"\r\n\r\n")
    appendString("\r\n")
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"maxHeight\"\r\n\r\n")
    appendString("\r\n")
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"quality\"\r\n\r\n")
    appendString("85\r\n")
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"format\"\r\n\r\n")
    appendString("\r\n")
    let image_fileData = try! Data(contentsOf: URL(fileURLWithPath: "localfile_path.png"))
    appendString("--\(boundary)\r\n")
    appendString("Content-Disposition: form-data; name=\"image_file\"; filename=\"localfile_path.png\"\r\n")
    appendString("Content-Type: application/octet-stream\r\n\r\n")
    body.append(image_fileData)
    appendString("\r\n")
    appendString("--\(boundary)--\r\n")
    request.addValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")
    request.httpBody = body
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
      defer { semaphore.signal() }
      guard let data = data else {
        print(String(describing: error))
        return
      }
      print(String(data: data, encoding: .utf8)!)
    }
    task.resume()
    semaphore.wait()
    
  • 常见问题 Q&A

    • Q: 数据请求有缓存吗?

      A: 我们为所有数据请求提供实时响应。对于定期更新的数据,我们在其更新周期内实施缓存策略,以优化性能。

    • Q: 如何保证请求时 key 的安全性?

      A: 我们建议将对 API 的请求操作放置在您的应用程序后端。这样,前端请求只与您的后端服务交互,确保了更高的安全性和易于维护的架构。

    • Q: 接口可以用于哪些开发语言?

      A: 我们的接口支持所有能进行网络请求的开发语言,便于在各类项目中快速整合数据。

    • Q: 接口的性能可以保证吗?

      A: 我们的接口后台使用与商业级项目相同的架构,保证了稳定且高效的性能。您可以通过访问测试接口了解更多性能信息。

  • 服务协议以及服务免责声明

    用户应当充分阅读 服务协议 以及 服务免责声明 ,用户购买与使用咕咕数据 API 服务亦视为接受本协议。

  • 技术支持

    • 技术支持邮箱: support@gugudata.com
    • 微信客服: 客服链接

业务相关接口推荐

稳定提供服务 10 年 通用 PDF 文件流 OCR 到文本
  • 高可用图像识别引擎
  • 基于机器学习 / 高效文本提取
  • 1999元/年限时折扣 999元/年
查看详情 被调用于 2 秒前
50% 折扣
稳定提供服务 10 年 PPT 转高精度图片
  • 将 PPT 文件转换为图片序列
  • 文件转换 / 图片处理
  • 999元/年限时折扣 499元/年
查看详情 被调用于 8 秒前
50% 折扣
PDF 转 HTML
  • 高效 PDF 转 HTML 工具
  • 生成HTML站点 / 可永久存储
  • 999元/年限时折扣 499元/年
查看详情 被调用于 9 秒前
50% 折扣
PDF 分割拆分
  • 高效的 PDF 分割工具
  • 高效处理 / 可永久存储
  • 999元/年限时折扣 499元/年
查看详情 被调用于 5 秒前
50% 折扣