使用指南

# 交互式登录，会把 API Key 写入本机配置
somark login

# 也可以直接设置、读取和查看配置
somark config set api_key sk-your-api-key
somark config get api_key
somark config list

# 临时使用时，环境变量更轻便
export SOMARK_API_KEY=sk-your-api-key

from somark import SoMark

# 显式传参最清楚，也最适合服务端程序
client = SoMark(
    api_key="sk-your-api-key",
    base_url="https://somark.ai/api/v1",
    timeout=60,
    max_retries=2,
)

import { SoMark } from 'somark-js'

// JavaScript 使用 camelCase 参数名
const client = new SoMark({
  apiKey: 'sk-your-api-key',
  baseUrl: 'https://somark.ai/api/v1',
  timeout: 60,
  maxRetries: 2,
})

import warnings
from somark import SoMark, SoMarkWarning

# 如果你不希望 Python 程序显示 SoMark warning，可以用 warnings 库过滤
warnings.filterwarnings("ignore", category=SoMarkWarning)

client = SoMark(api_key="sk-your-api-key")
response = client.parser.parse(file="./document.pdf")

print(response.warnings)  # list[str]

import { SoMark } from 'somark-js'

// Node.js 会通过 process warning 通道收到 SoMarkWarning
process.on('warning', (warning) => {
  if (warning.name === 'SoMarkWarning') {
    console.warn(warning.message)
  }
})

const client = new SoMark({ apiKey: 'sk-your-api-key' })
const response = await client.parser.parse({ file: './document.pdf' })

console.log(response.warnings) // string[]

# 单格式不传 --out：结果写到 stdout，适合管道和脚本
somark parse ./document.pdf --formats md

# 安静模式：关闭 SoMark warning 输出
somark --no-warnings parse ./document.pdf --formats md

# 单格式写入指定文件；父目录必须已经存在
somark parse ./document.pdf --formats md --out ./document.md

# 多格式必须写入已存在目录；会生成 parsed/document.md 和 parsed/document.json
mkdir -p ./parsed
somark parse ./document.pdf --formats md,json --out ./parsed/

# 多个文件用空格分隔；批量输出目录也必须提前创建
mkdir -p ./parsed
somark parse ./a.pdf ./b.pdf --out ./parsed/

# 也可以从清单读取，每行一个文件路径
mkdir -p ./parsed
somark parse --file-list ./files.txt --out ./parsed/

# 输出 Markdown，并打开标题层级识别和 HTML 表格
somark parse ./paper.pdf --formats md --title-levels --table-fmt html

from pathlib import Path
from somark import SoMark, ExtractConfig, ElementFormats

client = SoMark(api_key="sk-your-api-key")

# formats 可以写 md/json/zip；SDK 会映射到 API 字段
response = client.parser.parse(
    file="./document.pdf",
    formats=["md", "json"],
    element_formats=ElementFormats(
        image="url",
        formula="latex",
        table="html",
        cs="image",
    ),
    extract_config=ExtractConfig(
        enable_title_level_recognition=True,
        enable_table_cross_page=True,
    ),
)

# save 可写入文件，或写入已存在目录
response.save("./document.md")
Path("./parsed").mkdir(exist_ok=True)
response.save("./parsed", format=["md", "json"])

# 不保存时，直接读取响应字段
print(response.md)
print(response.json_output)
print(response.zip_url)

# 多文件传列表，返回值也是列表，顺序和输入一致
responses = client.parser.parse(
    file=["./a.pdf", "./b.pdf"],
    formats=["md"],
)
for source, item in zip(["./a.pdf", "./b.pdf"], responses):
    item.save(source.replace(".pdf", ".md"))

# 读取清单文件：每行一个文件路径，相对路径按当前运行目录解析
responses = client.parser.parse(
    file="./files.txt",
    file_list=True,
    formats=["md"],
)

import * as fs from 'fs'
import { SoMark } from 'somark-js'

const client = new SoMark({ apiKey: 'sk-your-api-key' })

// formats 支持 md/json/zip；JS 参数使用 camelCase
const response = await client.parser.parse({
  file: './document.pdf',
  formats: ['md', 'json'],
  elementFormats: {
    image: 'url',
    formula: 'latex',
    table: 'html',
    cs: 'image',
  },
  extractConfig: {
    enableTitleLevelRecognition: true,
    enableTableCrossPage: true,
  },
})

// save 可写入文件，或写入已存在目录
response.save('./document.md')
fs.mkdirSync('./parsed', { recursive: true })
response.save('./parsed', ['md', 'json'])

// 不保存时，直接读取响应字段
console.log(response.md)
console.log(response.jsonOutput)
console.log(response.zipUrl)

// 多文件传数组，返回值也是数组，顺序和输入一致
const responses = await client.parser.parse({
  file: ['./a.pdf', './b.pdf'],
  formats: ['md'],
})

responses.forEach((item, index) => {
  item.save(index === 0 ? './a.md' : './b.md')
})

// 读取清单文件：每行一个文件路径，相对路径按当前运行目录解析
const listResponses = await client.parser.parse({
  file: './files.txt',
  fileList: true,
  formats: ['md'],
})

# 1. 提交任务，只拿 task_id，不等待结果
somark parse ./large.pdf --async --formats md,json

# 一次提交多个文件，每个文件都会得到独立的 task_id
somark parse ./a.pdf ./b.pdf --async --formats md

# 也可以从清单读取
somark parse --file-list ./files.txt --async --formats md

# 2. 等待已有任务完成，并把结果保存到本地
somark parse --task-id task_xxx --wait --out ./large.md

# 3. 只查一次状态，不阻塞等待
somark parse --task-id task_xxx

from somark import SoMark

client = SoMark(api_key="sk-your-api-key")

# create 只提交任务，适合放进队列或后台流程
task = client.parser.create(file="./large.pdf", formats=["md"])
print(task.id)

# 多文件提交会返回 list[Task]
tasks = client.parser.create(file=["./a.pdf", "./b.pdf"], formats=["md"])
for task in tasks:
    print(task.id)

# 清单文件同样支持
tasks = client.parser.create(file="./files.txt", file_list=True, formats=["md"])

# wait 会定时轮询 async_check，直到成功、失败或超时
result = task.wait(poll_interval=3.0, timeout=120.0)
result.save("./large.md")

import { SoMark } from 'somark-js'

const client = new SoMark({ apiKey: 'sk-your-api-key' })

// create 只提交任务，马上返回 task id
const task = await client.parser.create({
  file: './large.pdf',
  formats: ['md'],
})

console.log(task.id)

// 多文件提交会返回 Task[]
const tasks = await client.parser.create({
  file: ['./a.pdf', './b.pdf'],
  formats: ['md'],
})

tasks.forEach((item) => console.log(item.id))

// 清单文件同样支持
const listTasks = await client.parser.create({
  file: './files.txt',
  fileList: true,
  formats: ['md'],
})

// wait 会定时轮询 async_check，直到成功、失败或超时
const result = await task.wait({ pollInterval: 3, timeout: 120 })
result.save('./large.md')

# 默认用表格显示，适合人眼查看
somark usage

# JSON 更适合脚本读取
somark usage --format json

# text 输出更轻，适合日志
somark usage --format text

from somark import SoMark

client = SoMark(api_key="sk-your-api-key")

# 返回的是结构化对象，字段名使用 Python snake_case
usage = client.usage.get()

print(usage.remaining_paid_pages)
print(usage.remaining_free_pages_today)
print(usage.remaining_free_pages_this_month)
print(usage.dashboard_url)

import { SoMark } from 'somark-js'

const client = new SoMark({ apiKey: 'sk-your-api-key' })

// 返回的是结构化对象，字段名使用 JavaScript camelCase
const usage = await client.usage.get()

console.log(usage.remainingPaidPages)
console.log(usage.remainingFreePagesToday)
console.log(usage.remainingFreePagesThisMonth)
console.log(usage.dashboardUrl)

# 预览 SoMarkDown 文件，并自动打开浏览器
somark preview ./document.smd

# 指定本地服务监听地址和端口
somark preview ./document.md --host 127.0.0.1 --port 7878

# 只启动服务，不自动打开浏览器
somark preview --no-open

from somark import SoMarkDownPreview

preview = SoMarkDownPreview()

# 启动本地预览服务；不需要 API Key
server = preview.start(
    file="./document.smd",
    host="127.0.0.1",
    port=7878,
    open_browser=True,
)

print(server.file_url)

# 脚本结束前主动停止服务
server.stop()

import { SoMarkDownPreview } from 'somark-js'

const preview = new SoMarkDownPreview()

// 启动本地预览服务；不需要 API Key
const server = await preview.start({
  file: './document.smd',
  host: '127.0.0.1',
  port: 7878,
  openBrowser: true,
})

console.log(server.fileUrl)
await server.stop()

# 把 PDF 每一页转成图片，输出到当前目录
somark pdf toimg ./document.pdf

# 指定输出目录和分辨率
somark pdf toimg ./document.pdf --out ./pages --dpi 200

# 自定义图片文件名
somark pdf toimg ./document.pdf --format "{name}-{n}.png"

from somark import PDFProcessor

pdf = PDFProcessor()

# 本地处理，不消耗解析额度
result = pdf.to_images(
    file="./document.pdf",
    out="./pages",
    filename_format="{name}.page-{n}.png",
    dpi=200,
)

print(result.files)

import { PDFProcessor } from 'somark-js'

const pdf = new PDFProcessor()

// 本地处理，不消耗解析额度
const result = await pdf.toImages({
  file: './document.pdf',
  out: './pages',
  filenameFormat: '{name}.page-{n}.png',
  dpi: 200,
})

console.log(result.files)