AI 驱动的出海方法论

您的 AI 读不懂您的产品手册,但您还在付费。

词元流 TokenFlow 将杂乱输入(PDF、Word、表格、音频、网页)转换为您的系统真正能用的结构化文本。

词元流是铁狮国际(Iron Lion International)旗下为中国出海企业打造的文档转换 API。您可以把数百份产品手册、SKU 表格、客户反馈录音一次性交给 API,拿回干净、可直接喂给 AI 的 Markdown 或 HTML。无需自己写解析器,无需逐份手动处理。

微信二维码,长按识别添加铁狮国际出海顾问

扫码咨询,工作日2小时内回复

词元流 TokenFlow

产品概述

API 基础地址:https://tokenflow.fly.dev。您只需上传文件或传入 URL,即可在响应中获得结构化文本,直接用于 AI 智能体、知识库或内容 pipeline。

文档接入

将 PDF 或 DOCX 投入您的 AI 智能体,直接获得结构化 Markdown,无需编写解析器。

表格转文本

将 XLSX/CSV 转换为可读表格或结构化数据,方便 LLM 理解。

音频转录

WAV、MP3、OGG、FLAC、M4A → 带时间戳的文本。

URL 提取

粘贴链接,剥离广告与导航,获得正文内容。

压缩包批量处理

上传 ZIP,一次性处理多个文件,每个成功转换单独计入配额。

快速开始

以下代码示例保留英文原文,便于开发者直接复制使用。

curl -X POST "https://tokenflow.fly.dev/convert" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -F "file=@document.pdf" \
  -F "output_format=markdown"

返回示例:

{
  "markdown": "# Document Title

First paragraph..."
}

支持平台:OpenClaw、Hermes、任何能发起 HTTP POST 请求的系统。

认证

词元流使用 Bearer Token 认证。除 /health 外,每个请求都需要在请求头中携带 Authorization。

获取 API Key

  1. 访问 tokenflow.ironlion.cc 注册账号
  2. 在控制台复制您的 API Key
  3. 将 API Key 设置为环境变量 TOKENFLOW_API_KEY,或写入技能配置文件

使用 API Key

curl -H "Authorization: Bearer ${TOKE...EY}" \
  "https://tokenflow.fly.dev/usage"

多语言示例

JavaScript

const response = await fetch('https://tokenflow.fly.dev/convert', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  },
  body: formData
});

Python

import requests

headers = {"Authorization": f"Bearer {api_key}"}
response = requests.post(
    "https://tokenflow.fly.dev/convert",
    headers=headers,
    files={"file": open("doc.pdf", "rb")},
    data={"output_format": "markdown"}
)

错误:Key 无效

如果 Key 缺失或无效,您将收到:

{
  "error": "Unauthorized",
  "status": 401
}

请在控制台核对 Key 是否有效。Key 与您的账号及月度用量配额绑定。

API 端点

基础 URL:https://tokenflow.fly.dev。除 /health 外,所有端点均需要 Bearer 认证。

POST/convert

将文件转换为结构化文本。

请求示例

curl -X POST "https://tokenflow.fly.dev/convert" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -F "file=@document.pdf" \
  -F "output_format=markdown"

参数

  • file(File,必填)— 待转换的文件
  • output_format(String,选填)— "markdown"(默认)或 "html"

返回示例 — Markdown

{
  "markdown": "# Document Title

Content here..."
}

返回示例 — HTML

{
  "html": "

Document Title

Content here...

" }

返回示例 — ZIP 压缩包

{
  "filename": "archive.zip",
  "type": "zip",
  "results": [
    {
      "filename": "report.pdf",
      "status": "success",
      "markdown": "# Report

Content...",
      "input_tokens": 15000,
      "output_tokens": 8200,
      "output_chars": 32800,
      "meaningful": true
    },
    {
      "filename": "data.exe",
      "status": "skipped",
      "reason": "unsupported"
    },
    {
      "filename": "notes.docx",
      "status": "skipped",
      "reason": "quota_exceeded"
    }
  ],
  "total_files": 3,
  "converted_files": 1,
  "processing_time_ms": 2450
}

ZIP 内每次成功转换都会单独计入月度配额。配额耗尽时,剩余文件会以 "reason": "quota_exceeded" 跳过。不支持的文件(包括嵌套 ZIP)会以 "reason": "unsupported" 跳过。

错误返回

  • 400 — 不支持的格式或请求参数错误
  • 401 — API Key 无效或缺失
  • 413 — 文件过大
  • 429 — 配额用尽或被限流
  • 500 — 服务器错误
POST/convert/url

将网页转换为结构化文本。

请求示例

curl -X POST "https://tokenflow.fly.dev/convert/url" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

参数

  • url(String,必填)— 需要提取内容的 URL
  • output_format(String,选填)— "markdown"(默认)或 "html"

返回示例

{
  "markdown": "# Article Title

Article content..."
}
POST/convert/preview

在转换 XLSX 文件前获取所有工作表名称。适合需要让用户选择处理哪些工作表的场景。

请求示例

curl -X POST "https://tokenflow.fly.dev/convert/preview" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -F "file=@data.xlsx"

返回示例

{
  "sheets": ["Sheet1", "Sheet2", "Revenue 2024"]
}
GET/health

检查服务是否在线。无需认证。

请求示例

curl "https://tokenflow.fly.dev/health"

返回示例

{
  "status": "ok"
}
GET/usage

查询当前用量及配额。

请求示例

curl -H "Authorization: Bearer ${TOKE...EY}" \
  "https://tokenflow.fly.dev/usage"

返回示例

{
  "used": 1247,
  "quota": 5000,
  "reset_date": "2026-06-01"
}

支持的文件格式

词元流默认支持以下格式。无需插件或额外配置。

文档

  • .pdf — PDF 文档,保留版式提取文本
  • .docx — Microsoft Word 文档
  • .pptx — Microsoft PowerPoint 演示文稿
  • .html.htm — HTML 网页(本地文件)

表格

  • .xlsx — Microsoft Excel(支持多工作表)
  • .xls — 旧版 Excel 格式
  • .csv — 逗号分隔值

先用 /convert/preview 列出工作表名称,再传入 sheets="all" 或指定工作表名称。

数据文件

  • .json — JSON,格式化并校验
  • .xml — XML,保留标签结构
  • .txt — 纯文本,标准化后返回
  • .md — Markdown,原样返回

音频

  • .wav — WAV 音频 → 转录
  • .mp3 — MP3 音频 → 转录
  • .ogg — OGG 音频 → 转录
  • .flac — FLAC 音频 → 转录
  • .m4a — M4A 音频 → 转录

音频文件会被转录为文本。暂不支持说话人识别。

压缩包

  • .zip — ZIP 压缩包。每个支持的文件会被单独解压并转换。不支持的文件及嵌套 ZIP 会被跳过。每次成功转换都会计入配额。

输出格式

  • markdown(默认)— 干净、结构化的 Markdown。最适合 AI 智能体与 LLM 消费。
  • html — 结构化 HTML。适合需要网页渲染的场景。

在任何转换请求中设置 output_format

错误处理

词元流会快速失败并告诉您原因。以下是每个错误的含义及处理方式。

400 — Bad Request

不支持的文件格式或请求格式错误。请对照上方「支持的文件格式」检查扩展名。不支持嵌套 ZIP。

401 — Unauthorized

API Key 无效或缺失。请检查 TOKENFLOW_API_KEY 是否已设置且有效。

413 — Payload Too Large

文件超过大小限制。请压缩、拆分或减小文件后重试。

429 — Too Many Requests

配额用尽或被限流。请调用 /usage 查看配额,或等待重置后升级套餐。

500 — Server Error

我方服务端出现异常。请重试一次;如持续出现,请提交问题反馈。

504 — Gateway Timeout

转换耗时过长。请尝试使用更小的文件或更简单的格式后重试。

重试机制

词元流 OpenClaw / Hermes 技能会自动重试:

  • 限流(429):等待 1 秒后重试一次
  • 超时:maxRetries 配置重试(默认 1 次,可在技能配置中调整)
  • 5xx 错误:重试一次,之后进入回退逻辑

回退行为

转换失败时,技能可选择以下两种行为之一:

  • use_file(默认)— 直接透传原始文件,并记录警告
  • fail — 向用户报告错误并停止

config.json 中设置:

{
  "fallbackBehavior": "use_file"
}

提交问题反馈

通过词元流 Web 界面:点击右下角「支持」按钮打开帮助弹窗,描述问题并选择分类后提交 —— 工单会直接从界面创建。

通过 API:请在反馈中包含文件类型及大小、完整错误信息、请求 ID(来自响应头)。账户或账单问题,请发送邮件至 tokenflow@ironlioninternational.com

SDK 与集成

词元流可与智能体框架集成,也适用于任何 HTTP 客户端。

OpenClaw

安装技能:

openclaw skills install tokenflow

或手动复制到 ~/.openclaw/skills/tokenflow/。在 config.json 中配置:

{
  "apiKey": "your-api-key",
  "apiUrl": "https://tokenflow.fly.dev",
  "filetypeBehavior": {
    "docx": { "action": "convert", "askEachTime": false },
    "pdf":  { "action": "convert", "askEachTime": false },
    "xlsx": { "action": "convert", "askEachTime": true }
  },
  "outputFormat": "markdown",
  "maxRetries": 1,
  "fallbackBehavior": "use_file"
}

当用户上传支持的文件时,OpenClaw 会根据 filetypeBehavior 规则自动调用词元流。

Hermes

将技能目录复制到 ~/.hermes/skills/tokenflow/,使用与 OpenClaw 相同格式的 config.json。Hermes 智能体启动时会自动加载 skills 目录中的技能。

JavaScript / Node.js

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

async function convertFile(filePath, apiKey) {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('output_format', 'markdown');

  const response = await fetch('https://tokenflow.fly.dev/convert', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      ...form.getHeaders()
    },
    body: form
  });

  const data = await response.json();
  // ZIP 压缩包:data.type === 'zip',data.results 为数组
  if (data.type === 'zip') {
    return data.results.filter(r => r.status === 'success').map(r => r.markdown).join('

');
  }
  return data.markdown;
}

Python

import requests

def convert_file(file_path, api_key, output_format="markdown"):
    url = "https://tokenflow.fly.dev/convert"
    headers = {"Authorization": f"Bearer {api_key}"}

    with open(file_path, "rb") as f:
        files = {"file": f}
        data = {"output_format": output_format}
        response = requests.post(url, headers=headers, files=files, data=data)

    response.raise_for_status()
    return response.json()["markdown"]

# 转换 URL
def convert_url(target_url, api_key):
    url = "https://tokenflow.fly.dev/convert/url"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    response = requests.post(url, headers=headers, json={"url": target_url})
    response.raise_for_status()
    return response.json()["markdown"]

cURL 示例

转换 PDF

curl -X POST "https://tokenflow.fly.dev/convert" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -F "file=@report.pdf" \
  -F "output_format=markdown"

转换 URL

curl -X POST "https://tokenflow.fly.dev/convert/url" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

预览 XLSX 工作表

curl -X POST "https://tokenflow.fly.dev/convert/preview" \
  -H "Authorization: Bearer ${TOKE...EY}" \
  -F "file=@data.xlsx"

查询用量

curl -H "Authorization: Bearer ${TOKE...EY}" \
  "https://tokenflow.fly.dev/usage"

更新日志

  1. 2.1.0 — 当前版本

    • 新增 /convert/url 端点,支持网页内容提取
    • 新增 /convert/preview 端点,支持 XLSX 工作表发现
    • 新增 /usage 端点,支持配额追踪
    • 扩展音频支持:WAV、MP3、OGG、FLAC、M4A
    • 新增 ZIP 压缩包处理
    • 支持配置回退行为:use_filefail
    • 支持配置最大重试次数:maxRetries 0–3
  2. 2.0.0

    • API 迁移至 https://tokenflow.fly.dev
    • 新增 Bearer Token 认证
    • 新增 HTML 输出格式选项
    • 技能配置重构,支持按扩展名设置 filetypeBehavior
  3. 1.0.0

    • 首次发布
    • 支持 PDF、DOCX、PPTX、XLSX、CSV、JSON、XML、TXT、MD
    • 仅支持 Markdown 输出
    • 基础错误处理

需要技术支持?

词元流 API 文档以中文呈现,代码示例保留英文原文以便开发者直接使用。如需技术对接、企业批量处理方案或出海系统集成咨询,请联系我们。

微信二维码,长按识别添加铁狮国际出海顾问

长按识别二维码,添加专属顾问

企业接入咨询

适合需要批量处理、SDK 集成或出海系统对接的团队。填写后技术顾问将在工作日 2 小时内回电。

字段必填说明
姓名联系人全名
手机号+86 前缀自动填充;11 位验证;3-4-4 分隔
短信验证码6 位;60 秒冷却
公司名称企业全称
所属行业B2B 下拉选项,允许「其他」
预计月处理量<1,000 / 1,000–10,000 / 10,000–100,000 / >100,000
主要文件类型PDF / Word / Excel / 音频 / ZIP / URL 多选
您想咨询的问题最多 300 字

公司信息

铁狮国际 Tieshiguoji

  • 广州:广州市天河区 [PENDING 具体地址]
  • 加州:[PENDING 具体地址]
  • ICP 备案号:[PENDING]
  • 营业执照注册号:[PENDING]

服务状态:可调用 GET /health 检查。

常见问题

词元流支持哪些文件格式?

默认支持 PDF、DOCX、PPTX、HTML、XLSX、XLS、CSV、JSON、XML、TXT、MD,以及 WAV、MP3、OGG、FLAC、M4A 音频和 ZIP 压缩包。输出可选 Markdown 或 HTML。

API Key 在哪里获取?

访问 tokenflow.ironlion.cc 注册账号,在控制台复制您的 API Key。建议将其设置为环境变量 TOKENFLOW_API_KEY 或写入技能配置文件。

转换失败常见原因有哪些?

常见原因包括:不支持的文件格式、文件超过大小限制、月度配额用尽、扫描版 PDF 无 OCR 文本层、文件损坏或受密码保护、音频文件中无可用语音。

ZIP 压缩包如何计费?

ZIP 内每个被成功转换的文件都会单独计入月度配额。不支持的文件及嵌套 ZIP 会被跳过,不会计费。

如何查询当前用量?

调用 GET /usage 即可查看已用量、配额总量与重置日期。

有 SDK 或技能可以直接使用吗?

词元流提供 OpenClaw 与 Hermes 技能,也提供 JavaScript/Node.js、Python 与 cURL 示例,方便接入任何能发起 HTTP 请求的系统。

微信咨询电话咨询