Blurface API

Production-ready docs for the exact face blur workflow exposed in the playground.

Upload or host an image, create a face blur task, poll the result, then inspect history per API key. This page documents the public REST surface directly instead of wrapping it in abstract components.

Get API key Open playground Inspect logs

Base URL

https://blurface.net

Public endpoints are mounted on the same domain used by the web app.

Auth

Bearer API key

Every request expects Authorization: Bearer ....

Task model

Async create + poll

Create a task first, then poll status until the result image URL is returned.

Billing

0.5 credits / run

Credit is checked before submission. Failed upstream tasks are expected to settle through the backend policy.

Quick start

Ship your first request in minutes

The API accepts a public image URL. If your user starts in the playground, the browser flow uploads the file first and sends that hosted URL into the same public generate endpoint.

Step 1

Create task

Step 2

Poll status

Step 3

Use result URL

cURLQuick start

curl -X POST "https://blurface.net/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=1200&q=80&auto=format&fit=crop"
  }'

Authentication

Send a Bearer key on every request. Guest and signed-in users can both get a key through the playground flow.

Authorization: Bearer YOUR_API_KEY

Important input rule

The REST surface expects a public http(s) image URL. Raw file upload is handled by the app before the API call.

Lifecycle

How one task moves through the system

1. Input

Provide an image URL

Your app sends a public http(s) image URL. The playground gets this by uploading the original file first.

2. Submit

Create async task

The generate endpoint validates credits, forwards the request upstream, and returns a task ID immediately.

3. Poll

Watch for completion

Your client polls the status endpoint until the task becomes SUCCESS or FAILED.

4. Reuse

Inspect or store

Use the returned result URL in product flows and inspect the same task again from the logs endpoint.

POST/api/generate

Create a face blur task

Submit a public image URL and receive a task ID that can be polled later through the status endpoint.

Auth: Bearer API key

Credits: 0.5 credits

Parameters

Body / Query

Field	Type	Required
image body	string	Yes
public body	boolean	No
callback_url body	string	No

image: Public http(s) URL for the source image that should be processed. Example: https://example.com/source.jpg

public: Optional visibility flag reserved for downstream featured or public result flows. Example: false

callback_url: Optional http(s) webhook URL to keep with the task request. Example: https://your-app.com/webhooks/blurface

Integration notes

• The endpoint requires a public URL. Raw file bytes are not accepted here.
• Missing or invalid API keys return 401.
• Insufficient balance returns 402 before the task is created.

Example requestPOST

curl -X POST "https://blurface.net/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=1200&q=80&auto=format&fit=crop",
    "public": false
  }'

Example responseJSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n91abc123faceblur",
    "status": "IN_PROGRESS"
  }
}

GET/api/status

Check task status

Poll the task until completion. Successful responses return the result image URL inside the response field.

Auth: Bearer API key

Credits: No extra charge

Parameters

Body / Query

Field	Type	Required
task_id query	string	Yes

task_id: Task ID returned by the generate endpoint. Example: n91abc123faceblur

Integration notes

• Poll every 1 to 2 seconds for a balanced UX.
• When status becomes SUCCESS, response[0] contains the blurred image URL.
• When status becomes FAILED, inspect error_message and stop polling.

Example requestGET

curl -X GET "https://blurface.net/api/status?task_id=n91abc123faceblur" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example responseJSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n91abc123faceblur",
    "status": "SUCCESS",
    "consumed_credits": 0.5,
    "created_at": "2026-04-06T08:30:00Z",
    "request": {
      "image": "https://example.com/input.jpg"
    },
    "response": [
      "https://cdn.example.com/output.png"
    ],
    "error_message": null
  }
}

GET/api/list

List tasks created by the current API key

Load paginated task history for the Bearer API key you send with the request.

Auth: Bearer API key

Credits: No extra charge

Parameters

Body / Query

Field	Type	Required
page query	number	No
limit query	number	No
task_id query	string	No

page: Page number for pagination. Example: 1

limit: Number of records per page. Example: 10

task_id: Optional exact task filter when you want a single task by ID. Example: n91abc123faceblur

Integration notes

• This endpoint is ideal for dashboards, internal debugging, and customer support views.
• The returned logs are scoped to the API key used in Authorization.
• The web dashboard uses the same endpoint under the hood.

Example requestGET

curl -X GET "https://blurface.net/api/list?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example responseJSON

{
  "code": 200,
  "message": "success",
  "data": {
    "logs": [
      {
        "task_id": "n91abc123faceblur",
        "status": "SUCCESS",
        "consumed_credits": 0.5,
        "created_at": "2026-04-06T08:30:00Z",
        "request": {
          "image": "https://example.com/input.jpg"
        },
        "response": [
          "https://cdn.example.com/output.png"
        ],
        "error_message": null,
        "model": "image-face-blur"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 1
    }
  }
}

Errors

Status codes you should handle

HTTP	Meaning	Suggested action
400	Bad request or invalid input URL.	Validate image URL format and required parameters before retrying.
401	Missing or invalid API key.	Check the Bearer header or generate a fresh key from the dashboard.
402	Insufficient credits.	Top up the account or route the user back into the billing flow.
404	Task ID not found.	Verify the task ID and confirm it belongs to the current API key scope.
500	Internal or upstream service error.	Retry with backoff and log the request context for support.