接入 API · 格式工坊

這個 API 能做什麼、不做什麼#

包含文字與資料類格式：CSV / TSV / JSON / JSONL / Markdown / HTML / XML / 純文字。

不包含 圖片、PDF、音訊不在 API 裡。它們依賴瀏覽器的解碼器與畫布，伺服器做不到；那些轉換請在網頁裡完成，檔案不會上傳。

最快的一次呼叫#

curl · macOS / Linux

curl -sS https://www.file2file.net/api/v1/convert \
  -H 'content-type: application/json' \
  -d '{"from":"csv","to":"json","data":"id,name\n1,Alice\n2,Bob\n"}'

這段 curl 直接就能跑（網址就是本站）；Windows 上要寫 curl.exe —— PowerShell 裡 curl 是 Invoke-WebRequest 的別名、續行符也不是反斜槓，完整寫法見下面的「呼叫範例」頁籤。要換內容只改 -d 裡的 data；JSON 裡的換行寫成 \n。

基底網址與認證#

基底網址https://www.file2file.net

沒有 token、沒有註冊、沒有 API key。防護靠的是請求體上限、單 IP 突發額度與方法白名單 —— 詳見下面的限制一節。

允許跨域呼叫（CORS），預檢請求由 OPTIONS 處理，因此可以直接在瀏覽器頁面裡 fetch 這個介面。

端點#

POST /api/v1/convert 轉換一段文字：請求主體裡給 from / to / data
GET /api/v1/formats 列出全部支援的轉換組合與限制
GET /api/v1/health 探活：回傳版本與目前時間

四個端點分工清楚：轉換、能力表、健康檢查、根路徑。能力表建議啟動時拉一次快取起來。

支援的轉換組合#

每一行的第二個格式就是請求裡的 to。

從	到	回傳類型	說明
<code>csv</code>	`json`	`application/json`	首行表頭 → 物件陣列
<code>csv</code>	`tsv`	`text/tab-separated-values`	逗號換定位字元
<code>csv</code>	`txt`	`text/plain`	表格攤平成文字
<code>tsv</code>	`csv`	`text/csv`	定位字元換逗號
<code>tsv</code>	`json`	`application/json`	定位字元表格 → 物件陣列
<code>json</code>	`csv`	`text/csv`	物件陣列 → 表格（表頭取聯集）
<code>json</code>	`tsv`	`text/tab-separated-values`	物件陣列 → 定位字元表格
<code>json</code>	`txt`	`text/plain`	JSON 攤平成文字
<code>jsonl</code>	`csv`	`text/csv`	一行一個物件 → 表格
<code>md</code>	`html`	`text/html`	Markdown 渲染成完整 HTML 文件
<code>md</code>	`txt`	`text/plain`	去掉標記只留正文
<code>html</code>	`txt`	`text/plain`	剝掉標籤取文字
<code>xml</code>	`txt`	`text/plain`	XML 取文字內容
<code>txt</code>	`html`	`text/html`	純文字包成 HTML（保留换行）

在瀏覽器裡試一下#

這段文字會送到伺服器做轉換（和網頁裡的檔案轉換不同 —— 那個永遠不上傳）。建議只放測試資料。

從到還沒送出請求

輸入 0

輸出 0

請求參數#

from、to、data 三個是必填；其餘可選，且都能放在查詢字串裡（管線與 curl 更省事）。

參數	位置	類型	必填	說明
<code>from</code>	請求體	`string`	必填	來源格式，例如 csv、markdown、html。
<code>to</code>	請求體	`string`	必填	目標格式，必須在 /api/v1/formats 列出的組合裡。
<code>data</code>	請求體	`string`	必填	要轉換的文字本身（不是檔案路徑）。
<code>eol</code>	查詢字串	`lf \| crlf`	可選	輸出換行：lf 或 crlf；預設 crlf（表格類格式更通用）。
<code>delimiter</code>	查詢字串	`string`	可選	表格輸出的分隔符（如 ; 或 \t）。
<code>bom</code>	查詢字串	`1`	可選	傳 1 時在輸出開頭寫 UTF-8 BOM（給 Excel 認）。
<code>format</code>	查詢字串	`raw`	可選	傳 raw 時直接回傳轉換結果本身，不帶 JSON 信封。

限制與公平使用#

限制	值
请求体上限	256 KB
最大行数	20000
单 IP 突发额度	30 / 60s

沒有 token 靠什麼守住

請求主體上限 + 行數上限（Workers 端硬性檢查）
同一來源 IP 的短時限流（Worker 內盡力而為）
Cloudflare 端的 Rate limiting rules / Bot Fight Mode / WAF 託管規則
不落地、不記錄請求內容：日誌裡只有方法、路徑、狀態與耗時

伺服器不保存請求內容，日誌裡只有方法、路徑、狀態碼與耗時。

錯誤碼#

錯誤碼	狀態碼	含義
bad_request	400	請求格式不對（缺少 from/to/data，或 from 與 to 不搭配）
unsupported_pair	400	不支援的轉換組合，見 GET /api/v1/formats
bad_json	400	data 不是合法的 JSON
empty_data	400	data 是空的
too_large	413	請求主體超過 262144 位元組
too_many_rows	413	行數超過 20000
unsupported_media	415	Content-Type 不支援（請用 application/json 或 text/*）
rate_limited	429	短時間內請求過多，請稍後再試
method_not_allowed	405	這個方法不支援
not_found	404	沒有這個介面
server_error	500	伺服器端轉換失敗

失敗（4xx / 5xx）

錯誤一律是同一個信封：ok 為 false，error.code 可以直接用來分支判斷，message 是給人看的英文說明。

失敗（4xx / 5xx）

{
  "ok": false,
  "error": {
    "code": "unsupported_pair",
    "message": "This pair is not supported. See /api/v1/formats for the list."
  }
}

呼叫範例#

curl -sS https://www.file2file.net/api/v1/convert \
  -H 'content-type: application/json' \
  -d '{"from":"csv","to":"json","data":"id,name\n1,Alice\n2,Bob\n"}'

# PowerShell: call curl.exe ("curl" is an alias for Invoke-WebRequest)
# Continue lines with a backtick, and escape each inner double quote with a backslash
curl.exe -sS https://www.file2file.net/api/v1/convert `
  -H "content-type: application/json" `
  -d '{\"from\":\"csv\",\"to\":\"json\",\"data\":\"id,name\n1,Alice\n2,Bob\n\"}'

# CMD: single quotes do not work either - one line, double quotes, escaped quotes
curl.exe -sS https://www.file2file.net/api/v1/convert -H "content-type: application/json" -d "{\"from\":\"csv\",\"to\":\"json\",\"data\":\"id,name\n1,Alice\n2,Bob\n\"}"

import requests

resp = requests.post(
    "https://www.file2file.net/api/v1/convert",
    json={"from": "csv", "to": "json", "data": "id,name\n1,Alice\n2,Bob\n"},
    timeout=15,
)
resp.raise_for_status()
print(resp.json()["data"])   # [{"id": "1", "name": "Alice"}, ...]

import json, urllib.request

payload = json.dumps({
    "from": "md", "to": "html",
    "data": "# Title\n\nBody with **bold**.\n",
}).encode()

req = urllib.request.Request(
    "https://www.file2file.net/api/v1/convert",
    data=payload,
    headers={"content-type": "application/json"},
)
with urllib.request.urlopen(req, timeout=15) as r:
    print(json.load(r)["data"])

const res = await fetch("https://www.file2file.net/api/v1/convert", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ from: "json", to: "csv", data: '[{"a":1,"b":2}]' }),
});
const { data } = await res.json();
console.log(data);

# text/* bodies are accepted too; from/to go in the query string
cat table.csv | curl -sS --data-binary @- \
  "https://www.file2file.net/api/v1/convert?from=csv&to=json"

# CSV in, CSV out with explicit LF endings
curl -sS --data-binary @table.csv \
  "https://www.file2file.net/api/v1/convert?from=csv&to=tsv&eol=lf" -o out.tsv

# Windows PowerShell: the same pipe, but curl.exe (see the curl.exe tab)
Get-Content table.csv -Raw | curl.exe -sS --data-binary @- "https://www.file2file.net/api/v1/convert?from=csv&to=json"

成功（200）

data 裡就是轉換結果；要原始文字而不是 JSON 信封時，加 ?format=raw。bytes 是 data 的位元組數；quota.remaining 是【你目前】這一分鐘的剩餘額度，範例裡的數字只是當時抓的。

成功（200）

{
  "ok": true,
  "api": "v1",
  "from": "csv",
  "to": "json",
  "mime": "application/json",
  "bytes": 89,
  "data": "[\n  {\n    \"id\": \"1\",\n    \"name\": \"Alice\"\n  },\n  {\n    \"id\": \"2\",\n    \"name\": \"Bob\"\n  }\n]\n",
  "quota": { "remaining": 49, "windowMs": 60000 }
}

信封裡的欄位

參數	說明
<code>ok</code>	true 表示成功，false 表示失敗（錯誤都在 error 裡）。
<code>data</code>	轉換結果文字。
<code>mime</code>	結果的 MIME 類型。
<code>bytes</code>	結果的位元組數（UTF-8）。
<code>quota</code>	你這條 IP 在視窗裡還剩多少次突發額度。
<code>error.code</code>	機器可判別的錯誤碼，見上面的錯誤碼表。
<code>error.message</code>	一句英文說明，給人和日誌看。