postkitty docs

Run this in a terminal. The plugin comes from the official Hermes plugin catalog.

hermes plugins install postkitty

Answer yes when Hermes asks about the Python dependencies and about turning the plugin on. This form skips both questions:

hermes plugins install postkitty --yes-deps --enable

Then open a new chat. Hermes loads a plugin's tools when the next chat starts.

You can also let Hermes install it. Send this message:

Install the postkitty plugin for me: run `hermes plugins install postkitty --yes-deps --enable` in the terminal. When it finishes, tell me to open a new chat so its tools load.

postkitty needs no API key and no account. Text needs none of the media tools: without ffmpeg it still writes and counts your text.

To check all of it at once, type this in a Hermes chat:

/postkitty doctor

It reports on Python, ffmpeg and ffprobe, caption support, OpenCV, Pillow, the face model and the output folder. Each problem comes with one line on how to fix it, and the last line says what works now: text, photos, video, captions.

In the new chat, name the platforms and give Hermes your draft or the full path of each file.

Use postkitty to turn this into posts for X, LinkedIn and Instagram and fix my wording: [your draft, or the path to a photo or video]

One job takes one photo or one video, or one of each, plus the text. For several photos Hermes runs postkitty once per photo. postkitty does not build a carousel.

Hermes replies with the path of a job folder. The files that passed every check are in ready/, one folder per platform. Open board.html to see each file next to its text, its alt text and its check results.

postkitty/<job>/
  ready/
    instagram/
    linkedin/
    x/
  board.html
  advice.md

The job folder is created under ./postkitty in the folder your Hermes session works in. Settings lets you change that.

Reads the inputs and plans the job. It creates the job folder, finds people, shots and scenes, and plans a framing for each platform target. It renders nothing, and it also works with text alone.

Returns. The job id, the facts about each input (kind, size, length, people, shots), the plan for each target (layout, trim, cover frame), the limits each platform sets, the counts of your text and the path of a preview image.

Counts each platform's text with that platform's real rule and writes the text files. Text that is over the limit on X, Threads or Bluesky is split into a numbered thread. Hermes calls it again with a rewritten draft until every platform reports ok, and again for every later change to the text.

Returns. For each platform: the count, the unit, the limit, ok, the overflow and the part that stays visible before the feed cuts the text off. It writes advice.md into the job folder and the post.txt, thread.txt and alt.txt files into ready/.

Renders every planned target, checks each file against the platform's published limits, repairs what fails and puts only passing files into ready/. It also writes the review board. A job with text only has nothing to render.

Returns. A table with one row per target. A file is ready to upload only when its status is ready or repaired. failed rows say what is wrong, skipped rows say which program is missing on your machine.

Renders one photo or video target again after you ask for a change: another layout, another person in focus, a trim, another cover frame or captions. It reuses the scan, so it is quick. When the new render fails, the earlier passing file stays in place.

Returns. The same table as postkitty_make, for that one target.

Checks a file that postkitty did not make against one platform target, without rendering anything. Files from make and redo are already checked.

Returns. Pass or fail, and every check that failed with the limit it broke.

Type these in a Hermes chat. They answer at once and do not use the model.

The same engine runs from a terminal, for scripts and cron jobs:

Three settings, all optional. Change them in the plugin's settings in Hermes.

Send JSON with text. platforms is optional and defaults to all eight. Set split_threads to false to get the overflow instead of a thread.

curl -s https://postkitty.mertkayacs.com/api/v1/text \
  -H "Content-Type: application/json" \
  -d '{"text": "We shipped postkitty 1.0 today.", "platforms": ["x", "bluesky"]}'

import requests

reply = requests.post(
    "https://postkitty.mertkayacs.com/api/v1/text",
    json={"text": "We shipped postkitty 1.0 today.", "platforms": ["x", "bluesky"]},
    timeout=30,
)
reply.raise_for_status()
for platform, result in reply.json()["platforms"].items():
    print(platform, result["count"], "of", result["limit"], "ok" if result["ok"] else "too long")

const reply = await fetch("https://postkitty.mertkayacs.com/api/v1/text", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "We shipped postkitty 1.0 today.", platforms: ["x", "bluesky"] }),
})
if (!reply.ok) throw new Error((await reply.json()).error.message)
const { platforms } = await reply.json()
for (const [platform, result] of Object.entries(platforms)) {
  console.log(platform, result.count, "of", result.limit, result.ok ? "ok" : "too long")
}

The reply has one entry per platform: count, limit, ok, the overflow, the part that stays visible in the feed, and the thread parts.

Send the file as multipart/form-data with a target, for example tiktok or instagram_feed. The reply says whether it passes and lists the checks that failed.

curl -s https://postkitty.mertkayacs.com/api/v1/check \
  -F "[email protected]" \
  -F "target=tiktok"

import requests

with open("clip.mp4", "rb") as clip:
    reply = requests.post(
        "https://postkitty.mertkayacs.com/api/v1/check",
        files={"file": clip},
        data={"target": "tiktok"},
        timeout=120,
    )
reply.raise_for_status()
print(reply.json())

const form = new FormData()
form.append("file", fileInput.files[0])
form.append("target", "tiktok")

const reply = await fetch("https://postkitty.mertkayacs.com/api/v1/check", { method: "POST", body: form })
if (!reply.ok) throw new Error((await reply.json()).error.message)
console.log(await reply.json())

Upload a photo or a video as files. GET /v1/limits says how many files a job takes. text, platforms, layout and focus are optional, and a job with text alone is fine. The call returns at once with the job id and its links. Ask for the job every two seconds until its status is done or failed, then download single files or the zip, which also holds the review board.

# 1. Start a job. The reply carries its id.
curl -s https://postkitty.mertkayacs.com/api/v1/jobs \
  -F "[email protected]" \
  -F "text=Meet the team behind the launch." \
  -F "platforms=instagram,bluesky"

# 2. Ask every two seconds until status is done or failed.
curl -s https://postkitty.mertkayacs.com/api/v1/jobs/JOB_ID

# 3. Download the finished files as one zip.
curl -s -o postkitty.zip https://postkitty.mertkayacs.com/api/v1/jobs/JOB_ID/download

# 4. Delete the job now instead of waiting.
curl -s -X DELETE https://postkitty.mertkayacs.com/api/v1/jobs/JOB_ID

import time
import requests

API = "https://postkitty.mertkayacs.com/api"

with open("team.jpg", "rb") as photo:
    reply = requests.post(
        f"{API}/v1/jobs",
        files={"files": photo},
        data={"text": "Meet the team behind the launch.", "platforms": "instagram,bluesky"},
        timeout=120,
    )
reply.raise_for_status()
job = reply.json()

while job["status"] in ("queued", "running"):
    time.sleep(2)
    job = requests.get(API + job["links"]["status"], timeout=30).json()

if job["status"] == "done":
    archive = requests.get(API + job["links"]["download"], timeout=120)
    with open("postkitty.zip", "wb") as out:
        out.write(archive.content)
else:
    print(job["error"]["message"], job["error"]["hint"])

requests.delete(API + job["links"]["status"], timeout=30)

const API = "https://postkitty.mertkayacs.com/api"

const form = new FormData()
form.append("files", fileInput.files[0])
form.append("text", "Meet the team behind the launch.")
form.append("platforms", "instagram,bluesky")

let job = await (await fetch(API + "/v1/jobs", { method: "POST", body: form })).json()
if (job.error) throw new Error(job.error.message)

while (job.status === "queued" || job.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 2000))
  job = await (await fetch(API + job.links.status)).json()
}

if (job.status === "done") {
  for (const file of job.files) console.log(file.path, API + file.url)
  console.log("Everything as one zip:", API + job.links.download)
} else {
  console.error(job.error.message, job.error.hint)
}

Every error has the same body. The message is one plain sentence and the hint says what to do next. Both are English, so branch on code if you translate.

{
  "error": {
    "code": "...",
    "message": "one plain sentence",
    "hint": "what to do"
  }
}

Two codes ask you to wait: rate_limited (HTTP 429) and queue_full (HTTP 503). Both send a Retry-After header with the seconds to wait.

• Uploads only. The API never fetches a URL.
• Photos can be JPEG, PNG, WebP or GIF; video can be MP4, MOV, MKV or WebM. Animated images are refused. GET /v1/limits returns every cap as a number: files per job, file sizes, video length and text length.
• Calls are rate-limited per visitor and hour.
• Your uploads are deleted when the job finishes. The finished files are deleted 60 minutes later, at the time in expires_at. DELETE removes them at once.
• Nothing is posted, published or shared.

Open a new chat. Hermes loads a plugin's tools when a chat starts, so the chat you installed from does not have them. If they are still missing, the plugin is not turned on: run hermes plugins enable postkitty.

ffmpeg or ffprobe is missing. Install ffmpeg, make sure ffmpeg and ffprobe run in your terminal, then ask again. On macOS the ffmpeg that Hermes brings has no ffprobe, and brew install ffmpeg adds it. Text and photos work without them.

The face model downloads once, on first use, and that needs a network connection. Go online and ask again. Text works without it.

Your ffmpeg build cannot draw subtitles. Install a build with libass (with Homebrew on macOS that is ffmpeg-full), or leave the captions out. /postkitty doctor shows this in its Captions row.

ffmpeg draws captions with the fonts installed on the machine, and a bare server or a container can have none. Install one (on Ubuntu, for example, sudo apt install fonts-dejavu-core) and ask again. If the message lists characters, no installed font has them: install a font for that script or take them out of the subtitle file. An emoji that no font has is left out, and the result says so. /postkitty doctor shows a missing font in its Captions row.

The row says which limit the file broke and that the repair did not fix it. Ask for another layout for that target; pad keeps the whole picture and fits most cases. The other targets keep their passing files.

Say who you mean by position: “the person on the left”, “the second person from the left”. See Focus.

Hermes shortens it and counts again. On X, Threads and Bluesky you can ask for a thread instead.

postkitty makes still photos and video. Give it one frame as a JPEG or PNG, or give it the clip as a video file.

Ask for a new run with the changed file. postkitty then scans it again and starts a new job.