Nền tảng FileConvertFree dành cho nhà phát triển

Tích hợp chuyển đổi tệp vào ứng dụng của bạn

Sử dụng FileConvertFree REST API để chuyển đổi PDF và hình ảnh trong ứng dụng, backend, tự động hóa hoặc quy trình nội bộ.

API v1: Tài liệu được công khai. Yêu cầu API cần tài khoản FileConvertFree Premium hoặc Pro đang hoạt động.

Mở bảng điều khiển Xem các gói Tài liệu API tương tác

URL cơ sở

REST API v1

https://fileconvertfree.com/api1

Xác thực

X-API-Key header

X-API-Key: fcf_live_••••••••

Bắt đầu nhanh

Đăng nhập vào tài khoản FileConvertFree.

Sử dụng gói Premium hoặc Pro đang hoạt động.

Mở Bảng điều khiển → Developer API → Tạo khóa API. Lưu khóa đầy đủ ngay vì khóa chỉ được hiển thị một lần.

Gửi khóa trong header X-API-Key với mỗi yêu cầu API được bảo vệ.

Gói và giới hạn API

Các giới hạn được dùng chung cho toàn bộ tài khoản API và tất cả khóa. Tạo thêm khóa không làm tăng hạn mức.

Premium

200 / day

200 yêu cầu mỗi ngày
30 yêu cầu / phút
200 MB kích thước tệp tối đa
3 khóa đang hoạt động max

Pro

400 / day

400 yêu cầu mỗi ngày
60 yêu cầu / phút
200 MB kích thước tệp tối đa
3 khóa đang hoạt động max

Quản lý khóa API

1. Tạo khóa

Trong phần Developer API của Bảng điều khiển, bạn có thể giữ tối đa 3 khóa API đang hoạt động. Đặt tên hữu ích như Production, Office App hoặc Staging.

2. Lưu ngay

Bí mật đầy đủ chỉ được hiển thị sau khi tạo hoặc tạo lại. FileConvertFree lưu hàm băm bảo mật, không lưu bí mật dạng rõ, nên không thể hiển thị lại toàn bộ khóa sau đó.

3. Tạo lại khóa

Tạo lại khóa sẽ tạo bí mật mới và thu hồi khóa cũ ngay lập tức. Cập nhật ứng dụng trước khi đóng hộp thoại chứa bí mật chỉ hiển thị một lần.

4. Thu hồi khóa

Thu hồi khóa nếu không còn cần thiết hoặc có khả năng đã bị lộ. Xác thực bằng khóa đó sẽ dừng ngay. Bản ghi khóa đã thu hồi được tự động xóa sau 7 ngày.

Quy tắc bảo mật

Không chia sẻ khóa API, không đăng lên GitHub, không đưa vào JavaScript chạy trên trình duyệt và không lưu trong mã nguồn công khai. Hãy lưu trong biến môi trường phía máy chủ hoặc trình quản lý bí mật. Nếu nghi ngờ khóa bị lộ, hãy tạo lại hoặc thu hồi ngay.

Endpoint khả dụng

Phương thức	Endpoint	Mục đích / tùy chọn
GET	`/v1/account/usage`	Đọc gói đã xác thực, trạng thái khóa, mức dùng hằng ngày, hạn mức còn lại và mức dùng giới hạn tốc độ.
GET	`/health`	Kiểm tra công khai tình trạng và phiên bản API.
POST	`/v1/pdf/to-word`	Chuyển một tệp PDF hợp lệ sang Word.
POST	`/v1/pdf/to-excel`	Chuyển một tệp PDF hợp lệ sang Excel.
POST	`/v1/image/to-text`	Trích xuất văn bản OCR từ hình ảnh. Trường multipart tùy chọn: fast=true\|false.
POST	`/v1/image/to-word`	Chuyển hình ảnh sang Word. Trường multipart tùy chọn: fast=true\|false.
POST	`/v1/image/to-excel`	Chuyển hình ảnh sang Excel. Trường multipart tùy chọn: fast=true\|false.
POST	`/v1/image/remove-background`	Xóa nền hình ảnh. Trường tùy chọn: format (mặc định png), transparent=true\|false, fast_mode=true\|false.

Ví dụ mã

import os import requests API_KEY = os.environ["FCF_API_KEY"] url = "https://fileconvertfree.com/api1/v1/pdf/to-word" with open("sample.pdf", "rb") as source: response = requests.post( url, headers={"X-API-Key": API_KEY}, files={"file": ("sample.pdf", source, "application/pdf")}, timeout=700, ) response.raise_for_status() with open("converted.docx", "wb") as out: out.write(response.content)

import { readFile, writeFile } from "node:fs/promises"; const key = process.env.FCF_API_KEY; const bytes = await readFile("scan.png"); const form = new FormData(); form.append("file", new Blob([bytes], { type: "image/png" }), "scan.png"); form.append("fast", "false"); const response = await fetch( "https://fileconvertfree.com/api1/v1/image/to-text", { method: "POST", headers: { "X-API-Key": key }, body: form } ); if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`); console.log(await response.json());

Sử dụng ví dụ JavaScript trong môi trường máy chủ/Node.js. Không để lộ khóa bí mật trong JavaScript frontend hoặc trình duyệt.

curl -X POST "https://fileconvertfree.com/api1/v1/pdf/to-excel" \ -H "X-API-Key: $FCF_API_KEY" \ -F "file=@sample.pdf" \ --output converted.xlsx

<?php $apiKey = getenv('FCF_API_KEY'); $ch = curl_init('https://fileconvertfree.com/api1/v1/image/to-word'); $file = new CURLFile(__DIR__ . '/scan.png', 'image/png', 'scan.png'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => ['X-API-Key: ' . $apiKey], CURLOPT_POSTFIELDS => ['file' => $file, 'fast' => 'false'], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 700, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if ($body === false || $status >= 400) { throw new RuntimeException('API request failed: HTTP ' . $status); } file_put_contents(__DIR__ . '/converted.docx', $body); curl_close($ch);

Tệp được hỗ trợ và xác thực

Endpoint PDF nhận tệp PDF thực. Endpoint hình ảnh nhận JPEG/JPG/JFIF, PNG, WebP, GIF, BMP và TIFF/TIF. API kiểm tra cả phần mở rộng lẫn chữ ký thực của tệp.

Cách API phản hồi

Endpoint chuyển đổi trả trực tiếp nội dung tệp đã chuyển đổi cho client. Image-to-text trả JSON. URL tải xuống nội bộ của các công cụ không được cung cấp cho client API.

Lỗi HTTP và ý nghĩa

Trạng thái	Ý nghĩa	Nguyên nhân thường gặp / cách xử lý
401	Thiếu khóa API hoặc khóa không hợp lệ, hết hạn hay đã bị thu hồi.	Kiểm tra X-API-Key. Nếu khóa đã bị thu hồi hoặc tạo lại, hãy thay bằng bí mật hiện tại.
403	Quyền truy cập API không hoạt động.	Tài khoản hiện không có gói Premium hoặc Pro đủ điều kiện đang hoạt động.
409	Thao tác với khóa xung đột với trạng thái hiện tại.	Ví dụ: cố tạo hơn 3 khóa đang hoạt động hoặc tạo lại một khóa không hoạt động.
413	Tệp tải lên quá lớn.	Sử dụng tệp trong giới hạn gói API (hiện tại 200 MB).
415	Loại nội dung không được hỗ trợ hoặc không khớp.	Dùng PDF hoặc hình ảnh được hỗ trợ và giữ đúng phần mở rộng; API cũng kiểm tra chữ ký tệp.
422	Nội dung yêu cầu không hợp lệ.	Tệp có thể rỗng hoặc dữ liệu multipart bắt buộc bị thiếu/không hợp lệ.
429	Quá nhiều yêu cầu.	Bạn đã đạt giới hạn mỗi phút hoặc hạn mức hằng ngày của tài khoản. Hãy thử lại sau hoặc sau khi hạn mức ngày được đặt lại.
5xx	Lỗi tạm thời của API hoặc dịch vụ chuyển đổi.	Hãy thử lại với cơ chế backoff. Lỗi hạ tầng/backend không bị tính vào hạn mức hằng ngày.

Cách tính hạn mức

Hạn mức hằng ngày và giới hạn mỗi phút được dùng chung cho mọi khóa của cùng tài khoản API. Tệp tải lên không hợp lệ/không hỗ trợ bị từ chối trước chuyển đổi không tiêu tốn hạn mức ngày. Lỗi máy chủ/hạ tầng được hoàn lại vào hạn mức. Yêu cầu đã được nhận để chuyển đổi có thể vẫn được tính nếu trình chuyển đổi phía sau trả lỗi 4xx từ phía client. Hạn mức ngày được đặt lại theo ngày lịch của máy chủ/cơ sở dữ liệu API.

Usage check: GET https://fileconvertfree.com/api1/v1/account/usage

Câu hỏi thường gặp

Tài khoản Free có thể dùng API không?

Không. Tài liệu được công khai, nhưng truy cập API hiện yêu cầu gói Premium hoặc Pro đang hoạt động.

Ba khóa có làm hạn mức tăng gấp ba không?

Không. Các khóa dùng chung hạn mức hằng ngày và giới hạn mỗi phút ở cấp tài khoản.

Tôi có thể lấy lại bí mật đã mất không?

Không. Khóa dạng rõ không được lưu. Hãy tạo lại khóa và lưu bí mật mới.

Điều gì xảy ra khi gói trả phí hết hạn?

Quyền truy cập API bị vô hiệu khi tài khoản không còn gói đủ điều kiện đang hoạt động. Gia hạn Premium hoặc Pro để khôi phục quyền truy cập.

Sẵn sàng tích hợp FileConvertFree?

Tạo khóa trong Bảng điều khiển, kiểm tra bằng endpoint usage, sau đó kết nối route chuyển đổi mà ứng dụng cần.

Mở bảng điều khiển Tài liệu API tương tác