Quick start

The Python and Node SDKs are not yet published, and the API is in early access. Everything below works against the API as it exists today; the SDK you get by email installs from source.

1. Get an API key

The API is in early access. Email hello@tellmark.si for an account. We set it up by hand and email you a one-time link that signs you in to your dashboard. Then create a key on the dashboard's API keys page.

The full key is shown once; store it somewhere your code can read it, for example as environment variables:

export TELLMARK_API_KEY="your-api-key"
export TELLMARK_API_BASE_URL="https://api.tellmark.si"

2. Install the Python SDK

The tellmark package is not yet on PyPI, so there is no pip install yet. Ask for it when you write and install it from the source you receive. It needs Python 3.10 or newer. On Windows, installing the watermark library's dependencies fails under the default code page; set UTF-8 mode first with set PYTHONUTF8=1.

3. Mark one image

import tellmark

result = tellmark.mark_image("input.png", "output.png", model="my-model-name")
print(result.wm_id)

output.png carries a signed C2PA manifest and an invisible watermark. The image itself is never sent to Tellmark: only its metadata (mime type, model name) and, once it is marked, its hash.

4. Log one text output

import tellmark

tellmark.log_text("the text your model generated", model="my-model-name", app_name="my-app")

Only a SHA-256 hash of the text is sent. The text itself never leaves your process.

5. Check the result

Drop output.png on your account's verify page (linked from your dashboard's verify page settings) or the free checker at /check to see the mark reported back.

Without an SDK: log a text output over HTTP

A text mark is one request, so you can make it from any language today. Hash the text with SHA-256 yourself; the text never leaves your process.

curl -X POST "https://api.tellmark.si/v1/marks" \
  -H "Authorization: Bearer $TELLMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"text","asset_sha256":"<sha256 of the text, 64 hex characters>","model":"my-model-name","app_name":"my-app"}'

Image marking needs the SDK: it embeds the watermark and builds the C2PA claim on your machine, and only sends the claim to be signed. The API reference lists every endpoint.

Node

The Node SDK (@tellmark/sdk) is not yet published either; it comes from the same source as the Python SDK. It needs Node 22 or newer. It marks images and logs text the same way:

import { logText, markImage } from "@tellmark/sdk";

const result = await markImage("input.png", "output.png", { model: "my-model-name" });
console.log(result.wmId);

await logText("the text your model generated", { model: "my-model-name", appName: "my-app" });

Set the same two environment variables as above, or pass apiKey and baseUrl directly. As with Python, the image itself is never sent, and only a SHA-256 hash of the text is sent.

One difference from the Python SDK: an image marked with the Node SDK does not yet carry a trusted timestamp. Without one, its signature only validates while the signing certificate is still valid. The Python SDK adds the timestamp, so use it for images that must keep validating after the certificate expires.