Signature detection API
One POST request locates visual signature marks in an image and returns a bounding box and a confidence score for each mark. You send either a public image URL or base64 image bytes.
A new account starts with 10 detection credits. The playground asks you to sign in, then calls the same API.
Endpoint
POST https://signature-detector.com/api/detect
Authenticate with the x-api-key header. Create the key from the dashboard after you sign up. Keep it on your server. A browser session that is already signed in can also call the route, which is what the playground does, but external integrations should send the key.
curl -X POST https://signature-detector.com/api/detect \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key_here" \
-d '{
"imageUrl": "https://example.com/document.jpg"
}'Replace imageUrl with imageBase64 when the file is not on a public URL. Do not send both. The playground uploads send raw base64, without the data-URL prefix. Both forms are accepted by the route.
Response
result.count is how many marks were returned. Each detection has a box, a confidence score, class, and class_name. The published example uses class 0 and the name signature. creditsRemaining is the balance after the call. detectionId is the id stored for that result.
{
"success": true,
"result": {
"detections": [
{
"bbox": {
"x1": 321.23,
"y1": 373.39,
"x2": 647.21,
"y2": 501.68
},
"confidence": 0.192,
"class": 0,
"class_name": "signature"
}
],
"count": 1,
"confidenceThreshold": 0.1
},
"creditsRemaining": 9,
"detectionId": "clxxxx"
}When the image bytes match a previous detection at the same threshold, the JSON also includes cached: true. That field is omitted on a fresh detection.
Errors worth branching on
- 400 — missing image, both image fields set, a URL that does not parse, or an empty base64 string. The body has
error. - 401 — missing or unknown API key, or no signed-in session.
- 402 — balance is below 1. The body includes
creditsandneedsPurchase: true. - 503 — the detection service did not accept the call. The credit is refunded.
- 500 — the detection service returned something the route could not use, or an unexpected failure.
There is no rate-limit check in the route. Throughput is still bounded by the detection service behind it. The route also does not enforce the playground's 10MB upload cap. That cap applies only to files chosen in the playground UI.
Pricing
- $10 per 100,000 credits, which is $0.0001 each. An image that is not served from cache spends 1 credit. A PDF spends 1 credit per page.
- 10 credits are added when the account is created.
- $1 minimum purchase. That is 10,000 credits. There is no subscription.
- Credits do not expire. The balance stays on the account until a detection spends it. A failed detection puts the credit back. Repeating an image or an identical PDF returns
cached: trueand does not spend a credit. On a PDF that hit iscreditsUsed: 0. - Buy credits from the dashboard or estimate a volume on the pricing page.
Full request notes live in the API docs. A worked Python and Node walkthrough is in How to use the Signature Detection API.
What to build on top
A count of zero is a useful unsigned flag, with the limits described on checking whether a document is signed. Boxes are enough to crop the mark for a reviewer. PDFs use a different body, documented on PDF signature detection.
FAQ
What does a request look like?
POST https://signature-detector.com/api/detect with header x-api-key and a JSON body. Provide exactly one of imageUrl or imageBase64. imageUrl must be an http or https URL the server can download with no extra credentials. imageBase64 is the image file encoded as base64. A data:image/...;base64, prefix is accepted and stripped. Sending neither field, or sending both, returns HTTP 400.
Can I set the confidence threshold?
Yes, on an image request. Send threshold as a number from 0 to 1. The default is 0.1, and the response reports the value that was used as result.confidenceThreshold. Detections below that cutoff are omitted. A value outside 0 to 1 is HTTP 400. PDF detection always uses 0.1 and does not apply this field.
How much does a detection cost?
A new detection spends 1 credit. Credits are $10 per 100,000, so one credit is $0.0001. Signup starts the account at 10 credits. The minimum purchase is $1 (10,000 credits). Credits do not expire. If the same image bytes were already detected, the response includes cached: true and no credit is spent. If the detector fails, the credit for that request is refunded.
Does this verify the signer?
No. The API reports where a visual signature mark was found. It does not compare the mark to a known signature, name the signer, or validate a cryptographic signature stored inside a PDF.
Are coordinates pixels?
The sample response uses values such as x1 321.23 and y1 373.39, which are absolute positions rather than a 0 to 1 ratio. Treat x1, y1 as the top-left and x2, y2 as the bottom-right of the box on the image you submitted.
Related reading
- PDF signature detection
Send pdfUrl or pdfBase64. pages, count, and creditsUsed are top-level.
- Check if a document is signed
Turn a detection count into a review decision without treating it as identity proof.
- How to call the API
Python and Node examples for imageUrl, imageBase64, and errors.
- Signature detection in Node.js
fetch, imageUrl, imageBase64, and the status codes worth branching on.
- Crop signatures from boxes
The API returns coordinates. Pillow or sharp writes the crop.
- Pricing
$10 per 100,000 credits. Images cost 1 credit. PDFs cost 1 credit per page.
Try it on your own file
Upload an image in the playground, or create an API key from the dashboard after signup. Read the API docs for the request fields.