Photo QR code (halftone)
Turn a photo into a scannable QR code: the picture is dithered into the modules themselves, in color or mono.
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
| Name | Type | Required | What 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).
Related tools
- QR code generator
Make a scannable QR code from any text or link, styled your way: colors, gradients, dot shapes, a logo and a frame.
qr-generate - QR code export (PNG, PDF, EPS, GIF, MP4, print size)
Export a styled QR code as PNG, JPEG, WebP, SVG, PDF or EPS at any pixel or print size, or as an animated GIF, APNG or MP4, checked by a decoder.qr-export - QR code matrix (modules as data)Encode text as a QR code and get the raw grid of modules, with the role of every cell, to draw it any way you like.
qr-matrix - .gitignore generatorBuild a .gitignore for the languages, editors and operating systems you use, merged without duplicates.
gitignore-generate - Animated QR code
Make a QR code that draws itself: an animated SVG in any style that ends as a complete, scannable code.qr-animate - ASCII banner text generatorTurn short text into large five-line banner letters for terminals, READMEs, logs and code comments.
ascii-banner