Persist images

Image persistence saves network-dependent images from Markdown as local files and rewrites their destinations as relative paths. Use it to archive SoMark results, import Markdown into a RAG system or knowledge base, migrate documents to another server or office platform, or view documents on an intranet or offline. This reduces the document’s dependency on remote image URLs, network availability, and access permissions.

Method	When to use it	Best for	Result
Request ZIP during parsing	Before parsing, or when you can parse again	Anyone who wants a complete package in one step	ZIP archive
Use the image persistence Skill	After you already have Markdown	Codex, Claude Code, and other agent users	`main.md` and `images/`
Run Python code directly	After you already have Markdown	Developers who want to run, integrate, or modify the logic	Local Markdown image package

Method 1: Request a ZIP during parsing

This method requires the fewest steps. Use it when you have not parsed the document yet or can parse it again. output_formats is an array. It can contain only zip (the ZIP contains the Markdown and images), or it can request both json and zip. After parsing, the API returns the ZIP download URL in data.result.outputs.zip.

Prepare the request

Prepare the source document and a SoMark API key. Do not store a real API key in your code repository.

Request ZIP and image file output

Include zip in output_formats. When output_formats includes zip, element_formats.image can only be set to file. The example below requests both zip and json outputs:

Python

import json
import requests

url = "https://somark.cn/api/v1/parse/sync"
data = {
    "output_formats": ["zip", "json"],
    "api_key": "sk-***",
    "element_formats": json.dumps({
        "image": "file",
        "formula": "latex",
        "table": "html",
        "cs": "image",
    }),
}

files = {"file": ("example.pdf", open("example.pdf", "rb"))}

response = requests.post(url, data=data, files=files)
print(response.json())

curl -X POST https://somark.cn/api/v1/parse/sync \
  -F "file=@example.pdf" \
  -F "output_formats=zip" \
  -F "output_formats=json" \
  -F "api_key=sk-***" \
  -F 'element_formats={"image":"file","formula":"latex","table":"html","cs":"image"}'

import { readFile } from "node:fs/promises";

const form = new FormData();
const file = new Blob([await readFile("example.pdf")], {
  type: "application/pdf",
});

form.append("file", file, "example.pdf");
form.append("output_formats", "zip");
form.append("output_formats", "json");
form.append("api_key", "sk-***");
form.append("element_formats", JSON.stringify({
  image: "file",
  formula: "latex",
  table: "html",
  cs: "image",
}));

const response = await fetch("https://somark.cn/api/v1/parse/sync", {
  method: "POST",
  body: form,
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

<?php
// Requires: composer require guzzlehttp/guzzle
require __DIR__ . "/vendor/autoload.php";

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post("https://somark.cn/api/v1/parse/sync", [
    "multipart" => [
        [
            "name" => "file",
            "contents" => fopen("example.pdf", "rb"),
            "filename" => "example.pdf",
        ],
        ["name" => "output_formats", "contents" => "zip"],
        ["name" => "output_formats", "contents" => "json"],
        ["name" => "api_key", "contents" => "sk-***"],
        [
            "name" => "element_formats",
            "contents" => json_encode([
                "image" => "file",
                "formula" => "latex",
                "table" => "html",
                "cs" => "image",
            ]),
        ],
    ],
]);

echo $response->getBody();

package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
    "path/filepath"
)

func check(err error) {
    if err != nil {
        panic(err)
    }
}

func main() {
    file, err := os.Open("example.pdf")
    check(err)
    defer file.Close()

    var body bytes.Buffer
    writer := multipart.NewWriter(&body)
    part, err := writer.CreateFormFile("file", filepath.Base(file.Name()))
    check(err)
    _, err = io.Copy(part, file)
    check(err)

    check(writer.WriteField("output_formats", "zip"))
    check(writer.WriteField("output_formats", "json"))
    check(writer.WriteField("api_key", "sk-***"))
    check(writer.WriteField(
        "element_formats",
        `{"image":"file","formula":"latex","table":"html","cs":"image"}`,
    ))
    check(writer.Close())

    request, err := http.NewRequest(
        http.MethodPost,
        "https://somark.cn/api/v1/parse/sync",
        &body,
    )
    check(err)
    request.Header.Set("Content-Type", writer.FormDataContentType())

    response, err := http.DefaultClient.Do(request)
    check(err)
    defer response.Body.Close()

    fmt.Println(response.Status)
    _, err = io.Copy(os.Stdout, response.Body)
    check(err)
}

// Requires: org.apache.httpcomponents.client5:httpclient5
import java.io.File;
import java.nio.charset.StandardCharsets;

import org.apache.hc.client5.http.classic.methods.HttpPost;
import org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.CloseableHttpResponse;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.core5.http.ContentType;
import org.apache.hc.core5.http.io.entity.EntityUtils;

public class ParseDocument {
    public static void main(String[] args) throws Exception {
        HttpPost request = new HttpPost(
            "https://somark.cn/api/v1/parse/sync"
        );
        request.setEntity(MultipartEntityBuilder.create()
            .addBinaryBody(
                "file",
                new File("example.pdf"),
                ContentType.APPLICATION_PDF,
                "example.pdf"
            )
            .addTextBody("output_formats", "zip")
            .addTextBody("output_formats", "json")
            .addTextBody("api_key", "sk-***")
            .addTextBody(
                "element_formats",
                "{\"image\":\"file\",\"formula\":\"latex\",\"table\":\"html\",\"cs\":\"image\"}",
                ContentType.APPLICATION_JSON
            )
            .build());

        try (
            CloseableHttpClient client = HttpClients.createDefault();
            CloseableHttpResponse response = client.execute(request)
        ) {
            System.out.println(EntityUtils.toString(
                response.getEntity(),
                StandardCharsets.UTF_8
            ));
        }
    }
}

require "json"
require "net/http"
require "uri"

uri = URI("https://somark.cn/api/v1/parse/sync")
request = Net::HTTP::Post.new(uri)

File.open("example.pdf", "rb") do |file|
  request.set_form([
    ["file", file, {
      filename: "example.pdf",
      content_type: "application/pdf"
    }],
    ["output_formats", "zip"],
    ["output_formats", "json"],
    ["api_key", "sk-***"],
    ["element_formats", JSON.generate({
      image: "file",
      formula: "latex",
      table: "html",
      cs: "image"
    })]
  ], "multipart/form-data")

  response = Net::HTTP.start(
    uri.hostname,
    uri.port,
    use_ssl: uri.scheme == "https"
  ) { |http| http.request(request) }

  puts response.body
end

Submit the document and wait

Call the sync parsing endpoint and inspect code in the response. A value of 0 means the request succeeded.

Download and inspect the ZIP

Read the URL from data.result.outputs.zip, download and extract the archive, then confirm that it contains Markdown and image files.ZIP URL in the response:

Markdown and image files after extraction:

View the output_formats parameter reference

Method 2: Use the image persistence Skill

Use the somark-localize-images Skill when you already have a .md or .markdown file whose Markdown images or HTML <img> elements still use HTTP(S) URLs. The current implementation is version 1.4.0. It requires Python 3.8 or later and Pillow>=9.4.0,<11.0.0.

Install the dependency

Install the dependency from the Skill directory you received:

python --version
python -m pip install -r <skill-directory>/requirements.txt

Trigger the Skill with natural language

In a Skill-capable agent, enter a prompt such as:

Use the SoMark image persistence Skill to process result.md.
Download remote images locally and replace their Markdown URLs with local relative paths.

Process one file

You can also run the bundled script directly:

python <skill-directory>/scripts/somark_localize_images.py result.md -o result

If you omit -o, the script creates a directory beside the input using the source filename. For example, result.md defaults to result/.

Process a directory

Pass a directory to recursively process all .md and .markdown files. Each document receives an isolated package:

python <skill-directory>/scripts/somark_localize_images.py input_docs -o output_docs

Batch mode continues after an individual document fails. It returns a nonzero exit code and lists the failed files. Do not put the batch output directory inside the input directory.

Before:

![Example image](https://example.com/image.png)

After:

![Example image](./images/image_001.jpg)

A single-file package has this structure:

result/
├── main.md
└── images/
    ├── image_001.jpg
    └── image_002.jpg

To verify the result, confirm that the command exits with code 0, target images in main.md use ./images/image_NNN.jpg, and every referenced image exists and is nonempty. Finally, open main.md in a local Markdown viewer and confirm that the images render.

Persisted Markdown images rendered offline

The Skill detects image formats from their content, decodes each image, and re-encodes every output as JPEG. Transparent areas use a white background. A repeated URL is downloaded once. The Skill writes the new main.md only after every image succeeds, and it never modifies the source Markdown.

Download and file protection options

Each HTTP request has a 60-second timeout and 3 retries by default. For a slow network, use --workers 2 --timeout 120 --retries 5.
Each image has a default 100 MB size limit. Use --max-image-mb to change it.
Use the repeatable --allowed-host <domain> option to restrict downloads. Redirect destinations are checked too.
The Skill refuses to overwrite existing Markdown or images with different content. Use --force only when replacement is intentional.
The Skill creates a directory package and does not create a ZIP automatically. Compress the verified output separately when needed.

Method 3: Reuse Python code directly

The following is a simplified example for the common single-Markdown-file workflow. It supports HTTP(S) images in Markdown and HTML <img> elements, converts downloaded images to JPEG, writes main.md and images/image_NNN.jpg, and leaves the source Markdown unchanged. Compared with the full Skill, this example omits directory batch processing, domain allowlists, concurrent downloads, maximum image size limits, fenced-code protection, and --force replacement. It refuses to use an existing output directory so that it cannot silently overwrite files. Install the dependency:

python -m pip install "Pillow>=9.4.0,<11.0.0"

Save this complete script as localize_somark_images.py:

View the complete Python script

#!/usr/bin/env python3
import argparse
import html
import re
import time
import urllib.error
import urllib.parse
import urllib.request
from io import BytesIO
from pathlib import Path

from PIL import Image, ImageOps, UnidentifiedImageError

MARKDOWN_IMAGE_RE = re.compile(
    r"!\[[^\]\r\n]*\]\(\s*(?:<(?P<angle_url>https?://[^>\r\n]+)>|"
    r"(?P<plain_url>https?://[^\s)\r\n]+))",
    re.IGNORECASE,
)
HTML_IMAGE_RE = re.compile(
    r"<img\b[^>]*?\bsrc\s*=\s*(?P<quote>[\"'])(?P<url>https?://.*?)(?P=quote)",
    re.IGNORECASE | re.DOTALL,
)
RETRYABLE_STATUS = {408, 425, 429, 500, 502, 503, 504}


def find_urls(markdown):
    spans = []
    for match in MARKDOWN_IMAGE_RE.finditer(markdown):
        group = "angle_url" if match.group("angle_url") else "plain_url"
        spans.append((match.start(group), match.end(group), html.unescape(match.group(group))))
    for match in HTML_IMAGE_RE.finditer(markdown):
        spans.append((match.start("url"), match.end("url"), html.unescape(match.group("url"))))
    spans.sort(key=lambda item: item[0])
    result = []
    previous_end = -1
    for span in spans:
        if span[0] >= previous_end:
            result.append(span)
            previous_end = span[1]
    return result


def download(url, timeout, retries):
    request = urllib.request.Request(
        url,
        headers={"Accept": "image/*,*/*;q=0.8", "User-Agent": "somark-image-example/1.0"},
    )
    for attempt in range(retries + 1):
        try:
            with urllib.request.urlopen(request, timeout=timeout) as response:
                content_type = response.headers.get_content_type().lower()
                if not (content_type.startswith("image/") or content_type == "application/octet-stream"):
                    raise ValueError(f"URL returned non-image content: {content_type}")
                return response.read()
        except urllib.error.HTTPError as error:
            if error.code not in RETRYABLE_STATUS or attempt == retries:
                raise
        except (urllib.error.URLError, TimeoutError, OSError):
            if attempt == retries:
                raise
        time.sleep(min(2**attempt, 8))
    raise RuntimeError("unreachable")


def to_jpeg(data, destination):
    try:
        with Image.open(BytesIO(data)) as opened:
            opened.seek(0)
            oriented = ImageOps.exif_transpose(opened)
            try:
                oriented.load()
                has_alpha = oriented.mode in {"RGBA", "LA"} or (
                    oriented.mode == "P" and "transparency" in oriented.info
                )
                if has_alpha:
                    rgba = oriented.convert("RGBA")
                    converted = Image.new("RGB", rgba.size, (255, 255, 255))
                    converted.paste(rgba, mask=rgba.getchannel("A"))
                    rgba.close()
                else:
                    converted = oriented.convert("RGB")
                try:
                    converted.save(destination, "JPEG", quality=95, subsampling=0, optimize=True)
                finally:
                    converted.close()
            finally:
                if oriented is not opened:
                    oriented.close()
    except (UnidentifiedImageError, OSError, ValueError) as error:
        raise RuntimeError(f"Invalid image: {error}") from error


def rewrite(markdown, spans, names):
    chunks = []
    cursor = 0
    for start, end, url in spans:
        chunks.append(markdown[cursor:start])
        chunks.append(urllib.parse.quote("./images/" + names[url], safe="/-._~"))
        cursor = end
    chunks.append(markdown[cursor:])
    return "".join(chunks)


def localize(input_path, output_dir, timeout, retries):
    input_path = input_path.resolve()
    output_dir = output_dir.resolve()
    if input_path.suffix.lower() not in {".md", ".markdown"} or not input_path.is_file():
        raise ValueError("Input must be an existing .md or .markdown file")
    if output_dir.exists():
        raise FileExistsError(f"Output directory already exists: {output_dir}")

    markdown = input_path.read_text(encoding="utf-8-sig")
    spans = find_urls(markdown)
    urls = list(dict.fromkeys(span[2] for span in spans))
    names = {url: f"image_{index:03d}.jpg" for index, url in enumerate(urls, start=1)}

    downloaded = {url: download(url, timeout, retries) for url in urls}
    output_dir.mkdir(parents=True)
    image_dir = output_dir / "images"
    image_dir.mkdir()
    try:
        for url in urls:
            to_jpeg(downloaded[url], image_dir / names[url])
        with (output_dir / "main.md").open("w", encoding="utf-8", newline="") as output:
            output.write(rewrite(markdown, spans, names))
    except Exception:
        for path in image_dir.glob("image_*.jpg"):
            path.unlink()
        raise


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("input", type=Path)
    parser.add_argument("-o", "--output-dir", type=Path)
    parser.add_argument("--timeout", type=float, default=60.0)
    parser.add_argument("--retries", type=int, default=3)
    args = parser.parse_args()
    output_dir = args.output_dir or args.input.with_suffix("")
    localize(args.input, output_dir, args.timeout, args.retries)
    print(f"Completed: {output_dir / 'main.md'}")


if __name__ == "__main__":
    main()

Run it:

python localize_somark_images.py result.md -o result

How to choose

You have not parsed the document yet: request a ZIP during parsing.
You already have Markdown and use an agent tool: use the image persistence Skill.
You need to integrate or modify the logic: reuse the Python code.

Overview

Quickstart

Ecosystem

Extensions

FAQs

Method 1: Request a ZIP during parsing

Method 2: Use the image persistence Skill

Download and file protection options

Method 3: Reuse Python code directly

How to choose

​Method 1: Request a ZIP during parsing

​Method 2: Use the image persistence Skill

​Download and file protection options

​Method 3: Reuse Python code directly

​How to choose

Method 1: Request a ZIP during parsing

Method 2: Use the image persistence Skill

Download and file protection options

Method 3: Reuse Python code directly

How to choose