Usage guide

# Interactive login writes the API key to local config
somark login

# You can also set, read, and inspect config directly
somark config set api_key sk-your-api-key
somark config get api_key
somark config list

# For temporary use, environment variables are lighter
export SOMARK_API_KEY=sk-your-api-key

from somark import SoMark

# Explicit parameters are clearest, especially for server-side programs
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 uses camelCase parameter names
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

# If you do not want Python programs to display SoMark warnings, filter them with 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 receives SoMarkWarning through the process warning channel
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[]

# One format without --out: writes to stdout, useful for pipes and scripts
somark parse ./document.pdf --formats md

# Quiet mode: hide SoMark warning output
somark --no-warnings parse ./document.pdf --formats md

# One format to a specific file; the parent directory must already exist
somark parse ./document.pdf --formats md --out ./document.md

# Multiple formats must go to an existing directory; creates parsed/document.md and parsed/document.json
mkdir -p ./parsed
somark parse ./document.pdf --formats md,json --out ./parsed/

# Separate multiple files with spaces; the batch output directory must also exist first
mkdir -p ./parsed
somark parse ./a.pdf ./b.pdf --out ./parsed/

# You can also read from a list file, one file path per line
mkdir -p ./parsed
somark parse --file-list ./files.txt --out ./parsed/

# Output Markdown with title-level recognition and HTML tables enabled
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 can be md/json/zip; the SDK maps them to API fields
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 can write to a file, or to an existing directory
response.save("./document.md")
Path("./parsed").mkdir(exist_ok=True)
response.save("./parsed", format=["md", "json"])

# If you do not save, read response fields directly
print(response.md)
print(response.json_output)
print(response.zip_url)

# Pass a list for multiple files; the returned value is also a list in input order
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"))

# Read a list file: one file path per line; relative paths resolve from the current working directory
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 supports md/json/zip; JS parameters use 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 can write to a file, or to an existing directory
response.save('./document.md')
fs.mkdirSync('./parsed', { recursive: true })
response.save('./parsed', ['md', 'json'])

// If you do not save, read response fields directly
console.log(response.md)
console.log(response.jsonOutput)
console.log(response.zipUrl)

// Pass an array for multiple files; the returned value is also an array in input order
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')
})

// Read a list file: one file path per line; relative paths resolve from the current working directory
const listResponses = await client.parser.parse({
  file: './files.txt',
  fileList: true,
  formats: ['md'],
})

# 1. Submit a task and only get task_id; do not wait for the result
somark parse ./large.pdf --async --formats md,json

# Submit multiple files at once; each file gets its own task_id
somark parse ./a.pdf ./b.pdf --async --formats md

# You can also read from a list file
somark parse --file-list ./files.txt --async --formats md

# 2. Wait for an existing task to finish and save the result locally
somark parse --task-id task_xxx --wait --out ./large.md

# 3. Query status once without blocking
somark parse --task-id task_xxx

from somark import SoMark

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

# create only submits the task, useful for queues and background flows
task = client.parser.create(file="./large.pdf", formats=["md"])
print(task.id)

# Multi-file submission returns list[Task]
tasks = client.parser.create(file=["./a.pdf", "./b.pdf"], formats=["md"])
for task in tasks:
    print(task.id)

# List files are supported too
tasks = client.parser.create(file="./files.txt", file_list=True, formats=["md"])

# wait polls async_check until success, failure, or timeout
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 only submits the task and returns the task id immediately
const task = await client.parser.create({
  file: './large.pdf',
  formats: ['md'],
})

console.log(task.id)

// Multi-file submission returns Task[]
const tasks = await client.parser.create({
  file: ['./a.pdf', './b.pdf'],
  formats: ['md'],
})

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

// List files are supported too
const listTasks = await client.parser.create({
  file: './files.txt',
  fileList: true,
  formats: ['md'],
})

// wait polls async_check until success, failure, or timeout
const result = await task.wait({ pollInterval: 3, timeout: 120 })
result.save('./large.md')

# Table output is the default and works well for humans
somark usage

# JSON is better for scripts
somark usage --format json

# text is lighter for logs
somark usage --format text

from somark import SoMark

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

# The return value is structured; field names use 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' })

// The return value is structured; field names use JavaScript camelCase
const usage = await client.usage.get()

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

# Preview a SoMarkDown file and open the browser automatically
somark preview ./document.smd

# Set the local service host and port
somark preview ./document.md --host 127.0.0.1 --port 7878

# Start only the service, without opening the browser
somark preview --no-open

from somark import SoMarkDownPreview

preview = SoMarkDownPreview()

# Start a local preview service; no API key required
server = preview.start(
    file="./document.smd",
    host="127.0.0.1",
    port=7878,
    open_browser=True,
)

print(server.file_url)

# Stop the service explicitly before the script exits
server.stop()

import { SoMarkDownPreview } from 'somark-js'

const preview = new SoMarkDownPreview()

// Start a local preview service; no API key required
const server = await preview.start({
  file: './document.smd',
  host: '127.0.0.1',
  port: 7878,
  openBrowser: true,
})

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

# Convert every page of a PDF to images in the current directory
somark pdf toimg ./document.pdf

# Set output directory and resolution
somark pdf toimg ./document.pdf --out ./pages --dpi 200

# Customize image filenames
somark pdf toimg ./document.pdf --format "{name}-{n}.png"

from somark import PDFProcessor

pdf = PDFProcessor()

# Local processing; does not consume parsing quota
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()

// Local processing; does not consume parsing quota
const result = await pdf.toImages({
  file: './document.pdf',
  out: './pages',
  filenameFormat: '{name}.page-{n}.png',
  dpi: 200,
})

console.log(result.files)