Photo QR code (halftone)

Turn a photo into a scannable QR code: the picture is dithered into the modules themselves, in color or mono.

1 The code and the photo

The text or link the code holds. Short links make finer pictures.

Choose a file or drop it here

You can also paste an image. Up to 100 MB.

The photo to show in the code. Faces and bold shapes work best; it is cropped to a square.
Error-correction level. H keeps the picture safest.
Use at least this version: larger codes show more of the photo. Left out: 7 or the smallest that fits.
"colour" keeps the photo's colors; mono draws it in two colors.
Photo contrast, from 0.5 to 2.
Photo brightness, from -0.5 to 0.5.
Detail
fine fixes only the center of each module (more picture); balanced fixes five sub-pixels (sturdier). A fine code that does not read back is made again as balanced.
Dark color (mono mode, and the corner eyes).
Light color (mono mode, and the quiet zone).
Quiet zone around the code, in modules.
Approximate width of the picture in pixels.
Read the code back with a decoder before returning it.

Use it from code or an agent

# 1. Upload the file. The reply ends with a line "ref  <id>/f1": that is the file reference.
curl -T sample.jpg https://setget.net/drop/

# 2. Run the tool with that reference. "wait" holds the reply for up to 30 seconds while the job runs.
curl -s https://setget.net/v1/tools/qr-photo \
  -H 'Content-Type: application/json' \
  -d '{"input":{"text":"https://setget.net","image":"DROP_ID/f1"},"wait":30}'

# 3. The reply is {"tool", "ms", "result", "files": [{"name", "size", "url", "ref"}], "job"}.
#    Download a result file from its "url", or pass its "ref" to another tool.
#    Still running after the wait? The reply is 202 with "job": follow it with
#    curl -s https://setget.net/v1/jobs/JOB_ID?wait=30
import json, urllib.parse, urllib.request

BASE = "https://setget.net"

def call(method, path, body=None, headers=None):
    request = urllib.request.Request(BASE + path, body, headers or {}, method=method)
    return json.load(urllib.request.urlopen(request))

def upload(path):
    """Step 1: upload a file and get its reference."""
    name = path.replace("\\", "/").rsplit("/", 1)[-1]
    with open(path, "rb") as handle:
        reply = call("PUT", "/drop/" + urllib.parse.quote(name), handle.read(), {"Accept": "application/json"})
    return reply["file"]["ref"]

# Step 2: run the tool with the reference.
body = {"input": {'text': 'https://setget.net', 'image': upload("sample.jpg")}, "wait": 30}
reply = call("POST", "/v1/tools/qr-photo", json.dumps(body).encode(), {"Content-Type": "application/json"})

# Step 3: a job that is still running comes back as {"job": ...}. Wait for it.
while "result" not in reply and reply.get("job", reply).get("status") in ("queued", "running"):
    reply = call("GET", "/v1/jobs/" + reply.get("job", reply)["id"] + "?wait=30")
if "error" in reply:
    raise SystemExit(reply["error"]["message"])
print(reply["result"])
for file in reply["files"]:   # result files: download from "url", or pass "ref" to another tool
    print(file["name"], file["size"], file["url"], file["ref"])
const BASE = "https://setget.net";

// Step 1: upload a file and get its reference. file: a File or Blob
// (in Node: new Blob([fs.readFileSync(path)])).
async function upload(file, name) {
  const response = await fetch(`${BASE}/drop/${encodeURIComponent(name)}`, {
    method: "PUT", headers: {Accept: "application/json"}, body: file,
  });
  return (await response.json()).file.ref;
}

// Step 2: run the tool with the reference.
let reply = await (await fetch(`${BASE}/v1/tools/qr-photo`, {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({input: {"text":"https://setget.net","image":await upload(file, "sample.jpg")}, wait: 30}),
})).json();

// Step 3: a job that is still running comes back as {job}. Wait for it.
while (!reply.result && ["queued", "running"].includes((reply.job || reply).status)) {
  reply = await (await fetch(`${BASE}/v1/jobs/${(reply.job || reply).id}?wait=30`)).json();
}
if (reply.error) throw new Error(reply.error.message);
console.log(reply.result);
for (const file of reply.files) console.log(file.name, file.size, file.url, file.ref);
1. Upload. Tool: drop
Arguments:
{
  "action": "create",
  "files": [
    {
      "name": "sample.jpg",
      "size": "<bytes>"
    }
  ]
}
PUT each file's bytes to its "upload.url" with the listed headers, and keep its "ref".
With a shell, one command does both: curl -T FILE https://setget.net/drop/

2. Run. Tool: run_tool
Arguments:
{
  "slug": "qr-photo",
  "input": {
    "text": "https://setget.net",
    "image": "DROP_ID/f1"
  }
}

3. The answer holds "result" and "files" (each with "url" and "ref").
If it holds a "job" that is still running instead, follow it. Tool: job
Arguments:
{
  "action": "wait",
  "id": "JOB_ID"
}
{
  "input": {
    "text": "https://setget.net",
    "image": "DROP_ID/f1"
  },
  "wait": 30
}

This is a file tool, so a call takes three steps: upload the file to get a reference, run the tool with that reference, then read the result and download its files. Uploads and results are public by link and expire after one hour.

Endpoint: POST /v1/tools/qr-photo. Over MCP: run_tool with slug: "qr-photo". Machine-readable: input schema, Markdown. Connect an agent.

Inputs

NameTypeRequiredWhat it does
text string yes The text or link the code holds. Short links make finer pictures.
image file yes The photo to show in the code. Faces and bold shapes work best; it is cropped to a square. In the API: a file reference such as DROP_ID/f1. Accepts: image.
error_correction string no Error-correction level. H keeps the picture safest. One of: L, M, Q, H. Default: "H".
min_version integer no Use at least this version: larger codes show more of the photo. Left out: 7 or the smallest that fits. From 1 to 25.
mode string no "colour" keeps the photo's colors; mono draws it in two colors. One of: colour, mono. Default: "colour".
contrast number no Photo contrast, from 0.5 to 2. Default: 1.0. From 0.5 to 2.
brightness number no Photo brightness, from -0.5 to 0.5. Default: 0.0. From -0.5 to 0.5.
detail string no fine fixes only the center of each module (more picture); balanced fixes five sub-pixels (sturdier). A fine code that does not read back is made again as balanced. One of: fine, balanced. Default: "balanced".
foreground string no Dark color (mono mode, and the corner eyes). Default: "#000000".
background string no Light color (mono mode, and the quiet zone). Default: "#ffffff".
margin integer no Quiet zone around the code, in modules. Default: 4. From 2 to 10.
size integer no Approximate width of the picture in pixels. Default: 1200. From 256 to 4000.
verify boolean no Read the code back with a decoder before returning it. Default: true.

Examples

A color photo code

Input
{
  "text": "https://setget.net",
  "image": "sample.jpg"
}
Result

Press the example button above to run it on the sample file.

Mono, finer detail

Input
{
  "text": "https://setget.net",
  "image": "sample.jpg",
  "mode": "mono",
  "detail": "fine"
}
Result

Press the example button above to run it on the sample file.

Questions

Will it really scan?
Every module keeps its center (and in balanced mode its middle cross) in the right color, which is what scanners read. Each result is read back by a decoder and says whether it passed. Test it with your phone before printing.
Which photos work best?
Faces, logos and bold shapes with good contrast. Busy, low-contrast photos come out as noise. Try the contrast and brightness inputs.
Why is the code bigger than usual?
More modules show more of the picture, so photo codes use at least version 7 (45 x 45 modules).