图片转换 API 参考

图片格式转换端点的完整参考——请求参数、支持的格式、尺寸调整选项和代码示例。

端点

POST /api/v1/images/convert

所需权限： image

请求

输入来源（选择一种）

字段	类型	来源
`file`	二进制	通过 multipart 上传文件
`image_url`	字符串 (URI)	公开的 HTTP/HTTPS URL
`image_base64`	字符串	Base64 编码的图片内容

使用 JSON 请求体时，请使用 image_base64（与 OCR 的 base64 不同）。提供 mime_type 和 file_name 以获得正确的输出。

输出格式

字段	必需	可选值
`output_format`	是	`jpeg`、`png`、`webp`、`avif`

可选参数

字段	类型	默认值	说明
`quality`	整数 (1–100)	85 (jpeg), 80 (webp), 50 (avif)	输出质量。值越高，质量越好，文件越大。PNG 忽略此参数。
`width`	整数 (1–10000)	—	输出宽度（像素）
`height`	整数 (1–10000)	—	输出高度（像素）
`fit`	字符串	`inside`	缩放方式：`inside`、`cover`、`fill`
`preserve_metadata`	布尔	`false`	保留安全的源文件元数据（EXIF 等）

Fit 模式

模式	行为
`inside`	在宽度×高度范围内等比缩放
`cover`	覆盖宽度×高度范围，裁剪超出部分
`fill`	拉伸至精确的宽度×高度

响应

响应字段

字段	类型	说明
`data.output.base64`	字符串	转换后的图片（base64）
`data.output.filename`	字符串	安全的输出文件名
`data.output.format`	字符串	输出格式
`data.output.size_bytes`	整数	输出文件大小
`data.input`	对象	源图片元数据
`data.metrics`	对象	大小对比（输入/输出字节、节省字节、压缩比）
`data.usage`	对象	计费信息（积分、像素工作量）
`data.resize`	对象	应用的缩放参数（或 `null`）

支持的转换

从 ↓ / 到 →	JPEG	PNG	WebP	AVIF
JPEG	✅	✅	✅	✅
PNG	✅	✅	✅	✅
WebP	✅	✅	✅	✅
AVIF	✅	✅	✅	✅
GIF	✅	✅	✅	✅
TIFF	✅	✅	✅	✅

GIF 和 TIFF 仅作为输入支持（静态、首帧/首页）。

代码示例

import requests
import base64

response = requests.post(
    "https://image-to-text.org/api/v1/images/convert",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "image_url": "https://example.com/photo.png",
        "output_format": "webp",
        "quality": 85,
    },
)

data = response.json()
if data["success"]:
    with open("output.webp", "wb") as f:
        f.write(base64.b64decode(data["data"]["output"]["base64"]))

图片转换 API 参考

On this page