API Documentation

Overview

apiai.me gives you a library of pre-built Tools — ready-to-use API endpoints for image generation, editing, background removal, video creation, and more. The workflow is always the same: configure and test in the Dashboard, then copy the generated curl command into your code. No manual request-building required.

You can also chain tools into Pipelines — the Dashboard generates a single curl for the whole chain, just like it does for individual tools.

All API responses are JSON unless the endpoint returns binary data (images, video). Errors follow a consistent format:

{ "error": "description of what went wrong" }

How It Works

curl -X POST https://apiai.me/api/process/remove-bg \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@photo.png" \
  --output result.png

Authentication

Sign up at apiai.me to create your account. Authentication is passwordless — you receive a one-time code by email, verify it, and receive a session token for the dashboard. Your api_key is shown once at registration; use it for all programmatic API calls.

Step 1 — Request a login code

curl -X POST https://apiai.me/api/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

{ "requires_verification": true, "email": "you@company.com" }

Step 2 — Verify the code and get your session

curl -X POST https://apiai.me/api/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "482916"}'

{ "session_token": "sess_...", "username": "you", "email": "you@company.com" }

Step 3 — Use your API key

Pass your API key in the X-API-Key header on every protected request.

X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If your key is compromised, you can regenerate it from the Dashboard — the old key is immediately invalidated.

Rate Limits

To protect service stability, the API enforces the following limits:

Execution requests (everything that runs a tool, flow, pipeline, or batch item) share a server-wide cap of 2 in-flight jobs to protect GPU/CPU resources. Lightweight reads (listing tools, fetching balance, etc.) share a separate cap of 10.

When you exceed the per-user concurrency limit, the API returns 429 Too Many Requests:

{ "error": "Too many concurrent requests. Maximum 2 in-flight requests per user." }

When the server is at full capacity, the API returns 503 Service Unavailable:

{ "error": "Server at capacity. Maximum 2 concurrent processing jobs. Please retry shortly." }

Wait for an in-flight request to complete before sending the next one, or use the Batch API for high-volume workloads — batched items are queued server-side and don't count against the concurrency limit.

Base URL

https://apiai.me/api

All endpoint paths below are relative to this base URL.

List Tools

curl https://apiai.me/api/workflows \
  -H "X-API-Key: ak_xxxx"

[
  {
    "id": 7,
    "slug": "greyscale",
    "name": "Greyscale",
    "description": "Convert image to greyscale",
    "endpoint": "/api/process/greyscale",
    "method": "POST",
    "type": "workflow",
    "accepted_inputs": ["image"],
    "required_inputs": ["image"],
    "response_type": "image",
    "output_types": ["image"],
    "params": [
      {
        "name": "style",
        "expose_name": "style",
        "description": "Visual style to apply",
        "default_value": "natural",
        "allowed_values": ["natural", "vivid"],
        "required": false,
        "is_image": false
      }
    ]
  },
  {
    "id": 3,
    "slug": "logo-digitalize",
    "name": "Logo Digitalize",
    "description": "Multi-step logo pipeline",
    "endpoint": "/api/pipeline/logo-digitalize",
    "method": "POST",
    "type": "pipeline",
    "params": []
  }
]

Run a Tool

curl -X POST https://apiai.me/api/process/your-tool-slug \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@photo.png" \
  --output result.png

curl -X POST https://apiai.me/api/process/your-tool-slug \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=a minimalist tech logo" \
  --output result.png

# Each tool exposes its own parameters. Get the exact param names
# (the "expose_name" field) from GET /api/workflows or the Dashboard.
curl -X POST https://apiai.me/api/process/your-tool-slug \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=aerial view of a coral reef" \
  -F "your-param=value" \
  -F "another-param=value" \
  --output result.mp4

curl -X POST https://apiai.me/api/process/your-tool-slug \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@photo1.png" \
  -F "image=@photo2.png" \
  -F "prompt=combine these images" \
  --output result.png

# Step 1 – submit and stream progress (-N disables curl buffering)
curl -N -X POST https://apiai.me/api/process/your-tool-slug/stream \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=aerial view of a coral reef"

# Each SSE line looks like:
# data: {"type":"starting","elapsed_ms":0}
# data: {"type":"processing","elapsed_ms":4200}
# data: {"type":"done","elapsed_ms":47300,"result_id":"a3f9...","content_type":"video/mp4"}

# Step 2 – download the result using the result_id from the done event
curl https://apiai.me/api/result/a3f9... \
  -H "X-API-Key: ak_xxxx" \
  --output result.mp4

curl -X POST https://apiai.me/api/process/your-tool-slug/estimate \
  -H "X-API-Key: ak_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"params": {"duration_sec": 8, "resolution": "1080p"}}'

# Response (formula-priced tool):
# {
#   "slug": "your-tool-slug",
#   "kind": "formula",
#   "estimate": 8.10,
#   "min": 0.10,
#   "max": 20.00,
#   "reconciled": false,
#   "note": "Cost varies with the params you submit. Actual charge is fixed at request time."
# }

Pipelines

A pipeline chains multiple tools into a single API call. There are two kinds:

• My Pipelines — pipelines you build yourself in the Dashboard node builder. Call via POST /api/flow/{slug}.
• Custom Pipelines — pipelines built for your account by our team. They appear in the Custom Pipelines section of the Dashboard with their own curl command and playground. Call via POST /api/pipeline/{slug}.

To build your own: open the Dashboard, go to My Pipelines, and click New Pipeline. The pipeline gets a slug you can call immediately from the API or from Batch.

Pipelines can go further — the example below chains a format converter, upscaler, background remover, and image enhancer to turn a raw in-store photo into a production-ready product image in a single API call.

curl -X POST https://apiai.me/api/pipeline/logo-digitalize \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@logo.png" \
  --output result.png

Batch Processing

Process multiple images through a single workflow in one request. The server queues all items, processes them in parallel, and provides real-time progress via SSE. Results are available as a ZIP download for 1 hour after completion; multiple downloads are allowed within that window.

curl -X POST https://apiai.me/api/batch \
  -H "X-API-Key: ak_xxxx" \
  -F "workflow=remove-bg" \
  -F "images=@photo1.png" \
  -F "images=@photo2.png" \
  -F "images=@photo3.png"

curl -X POST https://apiai.me/api/batch \
  -H "X-API-Key: ak_xxxx" \
  -F "workflow=flow:my-pipeline" \
  -F "images=@photo1.png" \
  -F "images=@photo2.png"

curl https://apiai.me/api/batch \
  -H "X-API-Key: ak_xxxx"

curl https://apiai.me/api/batch/42 \
  -H "X-API-Key: ak_xxxx"

curl -X POST https://apiai.me/api/batch/42/cancel \
  -H "X-API-Key: ak_xxxx"

curl https://apiai.me/api/batch/42/download \
  -H "X-API-Key: ak_xxxx" \
  --output results.zip

Batch progress is also streamed via SSE Events with event types batch_created and batch_progress.

Usage

curl https://apiai.me/api/usage \
  -H "X-API-Key: ak_xxxx"

Logs

curl https://apiai.me/api/logs?limit=20 \
  -H "X-API-Key: ak_xxxx"

SSE Events

const es = new EventSource('/api/events?key=ak_xxxx');
es.addEventListener('usage', () => { /* reload stats */ });
es.addEventListener('balance_update', e => console.log(JSON.parse(e.data)));

const resp = await fetch('/api/events', {
  headers: { 'X-API-Key': 'ak_xxxx' }
});
const reader = resp.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Billing

Payments are processed securely via Stripe. Each API call deducts from your account balance. When your balance is insufficient you'll receive a 402 Payment Required response.

curl https://apiai.me/api/account/balance \
  -H "X-API-Key: ak_xxxx"

{ "balance": 47.50 }

curl -X POST https://apiai.me/api/account/create-checkout \
  -H "X-API-Key: ak_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'

{ "url": "https://checkout.stripe.com/c/pay/..." }

{ "enabled": true, "amount": 50 }

curl -X PUT https://apiai.me/api/account/auto-refill \
  -H "X-API-Key: ak_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "amount": 50}'

curl -X POST https://apiai.me/api/account/regenerate-key \
  -H "X-API-Key: ak_xxxx"

{ "api_key": "ak_yyyy..." }

List Pipelines

curl https://apiai.me/api/flows \
  -H "X-API-Key: ak_xxxx"

Create Pipeline

curl -X POST https://apiai.me/api/flows \
  -H "X-API-Key: ak_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Pipeline",
    "slug": "my-pipeline",
    "workflow_ids": [3, 5]
  }'

curl -X POST https://apiai.me/api/flows \
  -H "X-API-Key: ak_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Generate & Remove BG",
    "slug": "gen-remove-bg",
    "workflow_ids": [3, 5],
    "flow_config": {
      "nodes": [
        {
          "id": "node_1",
          "workflow": "seedream-4",
          "params": {
            "prompt": {"source": "expose", "expose": "prompt", "required": true},
            "style": {"source": "fixed", "fixed": "photorealistic"}
          }
        },
        {
          "id": "node_2",
          "workflow": "remove-background",
          "params": {
            "image": {"source": "from_node", "from_node": "node_1", "is_image": true}
          }
        }
      ],
      "output_node": "node_2"
    }
  }'

Execute Pipeline

curl -X POST https://apiai.me/api/flow/gen-remove-bg \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=a cute dog on white background" \
  --output result.png

curl -X POST https://apiai.me/api/flow/my-pipeline \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@input.png" \
  --output result.png

curl -X POST https://apiai.me/api/flow/my-pipeline \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@input-1.png" \
  -F "image=@input-2.png" \
  --output result.png

curl -X POST https://apiai.me/api/flow/create-and-remove-bg \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=a cute dog on a white background" \
  --output result.png

curl -X POST https://apiai.me/api/flow/my-pipeline/debug \
  -H "X-API-Key: ak_xxxx" \
  -F "step_index=1" \
  -F "image=@input.png"

Quality Gates

Quality Gate

{
  "version": "1.0",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "answer": true,
  "response": "YES",
  "prompt": "Does this image contain a person?",
  "latency_ms": 312
}

curl -X POST https://apiai.me/api/v1/quality-gate \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=Does this image contain a person?" \
  -F "image=@photo.jpg"

curl -X POST https://apiai.me/api/v1/quality-gate \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=Is this text toxic or offensive?" \
  -F "text=Hello, this is a friendly message"

curl -X POST https://apiai.me/api/v1/quality-gate \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=Does this product image match the description?" \
  -F "image=@product.jpg" \
  -F "text=Red leather handbag with gold clasp"

curl -X POST https://apiai.me/api/v1/quality-gate \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=Is this article well-structured and free of factual errors?" \
  -F "url=https://example.com/blog/post-slug"

Moderation: Check Image

{
  "version": "1.0",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decision": "reject",
  "confidence": 0.97,
  "policy": "dog-only-v1",
  "reasons": [
    {
      "code": "NO_DOG_DETECTED",
      "message": "No dog detected in image"
    }
  ],
  "signals": {
    "dog_detected": false,
    "nsfw": false
  },
  "latency_ms": 412
}

{"error": {"code": "INVALID_IMAGE", "message": "Unsupported image type"}}

curl -X POST https://apiai.me/api/v1/moderation/check-image \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@photo.jpg" \
  -F "policy=nsfw"

curl -X POST https://apiai.me/api/v1/moderation/check-image \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@photo.jpg" \
  -F "policy=brand-safety"

curl -X POST https://apiai.me/api/v1/moderation/check-image \
  -H "X-API-Key: ak_xxxx" \
  -F "image=@photo.jpg" \
  -F "policy=dog-only-v1" \
  -F 'policy_prompt=Check whether the image contains a dog as the main subject'

curl -X POST https://apiai.me/api/v1/moderation/check-image \
  -H "X-API-Key: ak_xxxx" \
  -F "image_base64=$(base64 -i photo.jpg)" \
  -F "policy=nsfw"

curl -X POST https://apiai.me/api/v1/moderation/check-image \
  -H "X-API-Key: ak_xxxx" \
  -H "X-Request-ID: my-correlation-id-123" \
  -F "image=@photo.jpg"

Delete Pipeline

curl -X DELETE https://apiai.me/api/flows/42 \
  -H "X-API-Key: ak_xxxx"

{ "ok": true }

MCP Server

Use apiai.me directly from AI-enabled editors and local AI tools like VS Code (Copilot), Cursor, Windsurf, Ollama, and others that support the Model Context Protocol. No binary to install — just point your client at our hosted MCP endpoint.

{
  "servers": {
    "apiai": {
      "type": "http",
      "url": "https://apiai.me/api/mcp",
      "headers": {
        "X-API-Key": "ak_xxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "apiai": {
      "url": "https://apiai.me/api/mcp",
      "headers": {
        "X-API-Key": "ak_xxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "apiai": {
      "url": "https://apiai.me/api/mcp",
      "headers": {
        "X-API-Key": "ak_xxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "apiai": {
      "url": "https://apiai.me/api/mcp",
      "headers": {
        "X-API-Key": "ak_xxxx"
      }
    }
  }
}

"Generate a minimalist tech logo using apiai"
"Remove the background from this image (pass base64)"
"Run my create-and-remove-bg pipeline with prompt 'a cute dog'"
"What tools do I have access to?"
"Check my apiai balance"

Quality Monitoring (Auto-Eval)

Quality Monitoring lets an AI judge score the output of your pipelines, ad-hoc content, or remote URLs against a profile you define. Each evaluation produces a 0–100 score, optional per-dimension scores, a verdict (pass, review, or fail), written reasoning, and improvement hints. Everything is managed at eval.apiai.me using your existing apiai.me API key.

There are three ways to trigger an eval:

1. Auto-Eval — every run of an opted-in pipeline is scored automatically after it completes.
2. Monitors — the system periodically fetches a URL or RSS feed and scores new/changed content on a schedule.
3. Manual — POST /v1/eval/run with an image, text, or URL whenever you want a one-off score.

Results stream live to the dashboard, and verdicts can trigger email notifications to one or more recipients.

Eval Profiles

A profile is the “rubric” the AI judge uses. It defines what you care about in plain English, optional weighted scoring dimensions, which pipelines it should auto-score, and — for multi-input pipelines — how each input is referenced in the rubric.

Input Slots & Tokens

When a profile watches a pipeline, the eval service inspects that pipeline's parameter schema and creates one input slot per parameter. Each slot gets a generic, type-prefixed token you reference in the rubric — {image_1}, {image_2}, {prompt_1}, {image_mask_1}, etc. The pipeline's real parameter name (e.g. product_image) stays internal and is never shown to the judge, so a single rubric stays portable across pipelines with the same shape.

For each slot you choose:

• Original — the output is judged against this input (e.g. preserve geometry from the source photo, match the fabric from a swatch). Multiple originals are normal.
• Context — visible to the judge but not a comparison anchor (e.g. masks, control inputs, guidance prompts).
• Alias (optional) — a friendlier label shown alongside the token in the dashboard. Doesn't change the token itself.

Token ordinals are locked at profile creation time, driven by the watched pipeline's parameter order (required-first). If new parameters are added to the pipeline later they get fresh ordinals — existing tokens never shift, so a published rubric keeps meaning the same thing.

For auto-eval, when a pipeline run completes, each user-supplied input is forwarded to the eval service and bound to the matching slot by parameter name. The judge then receives the rubric (with tokens left in place so it can reference them in its reasoning) plus a typed manifest per slot.

Verdicts

The verdict is derived from the overall score and the profile's pass_threshold:

Billing

Each evaluation costs $0.02 by default (configurable per profile) and is deducted from your org balance. The cost is reserved up-front and refunded if the judge call fails. If your balance is insufficient, the eval is skipped — your pipeline run itself is not affected.

Manual Eval — POST /v1/eval/run

Score arbitrary content against a profile on demand. Authenticate with your apiai.me API key (X-API-Key). Submit as multipart/form-data:

At least one of image / image_base64 / text / url must be supplied. The response contains the full EvalResult (score, dimension scores, verdict, reasoning, improvement hints, latency, cost).

Monitors — proactive URL & RSS scoring

A Monitor points at a URL or RSS/Atom feed and periodically fetches and scores its content against a profile. Use them to track competitor pages, blog feeds, social posts, status pages, or any public content you care about — without writing your own scheduler.

Monitors store their own state (last_hash, seen_ids, last_run_at, last_status, last_error). For URL monitors, when the fetched HTML page exposes an og:image, the image is also pulled and attached so the judge can score prose and visuals together. Each item costs the same as a manual eval (the profile's eval_cost).

Monitors can also be triggered immediately from the dashboard (POST /v1/eval/monitors/:id/run) for testing.

Email Notifications

Add recipients (name + email) and choose which verdicts trigger an email. Whenever a saved eval result has a matching verdict, the system dispatches an email via MailerSend with the score, profile name, reasoning, and a link back to the result on eval.apiai.me.

Every dispatch — success or failure — is recorded in the Notifications log on the dashboard so you can see exactly what was sent and to whom. You can also fire a synthetic test email from any recipient row to verify the setup end-to-end.

Dashboard

Manage everything at eval.apiai.me — sign in with your apiai.me API key.

• Profiles — create and edit rubrics, set thresholds, choose which pipelines auto-eval watches.
• Results — live-streaming feed of every evaluated run. Each row shows the output, the score / verdict / dimension scores, the judge's reasoning, and an inputs panel where every bound input appears as a typed slot labeled with its token ({image_1}, {image_2}, …) and the pipeline's source field name. Filter by verdict, profile, or pipeline slug.
• Analytics — pass/review/fail rates and average scores grouped by profile and pipeline.
• Monitors — configure URL/RSS monitors, see last-run status, run on demand.
• Recipients & Notifications — manage who gets emailed for which verdicts and review delivery history.

Teams & Organizations

Every account belongs to an organization. By default your org is solo — just you. You can invite colleagues to join your org so they share your tool access, billing balance, and pipelines without needing separate accounts or separate billing.

Roles

How to invite someone

Shared billing

All API calls made by any member — regardless of role — are charged against the owner's balance. Members do not need to add funds separately. The owner can top up the balance from the Funds page and optionally enable auto-refill so the team never runs dry.

Managing your team

Everything is handled from the Team page in the Dashboard:

• Remove a member — click the remove button next to their name. Their API key is immediately invalidated.
• Change a role — use the role selector in the members table.
• Cancel a pending invite — click cancel next to the invitation before it is accepted.
• Rename your org — use the Organization name field at the bottom of the Team page. The name appears in invite emails.
• Leave a team — non-owner members can leave from the Team page. After leaving you are moved to a personal solo organization.

Team API

Every Team page action is also available through the API. All endpoints require X-API-Key and operate on the org of the calling key. Owner role is required for membership changes (invite, remove, role change, rename, cancel).

curl -X POST https://apiai.me/api/team/invite \
  -H "X-API-Key: ak_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"colleague@example.com","role":"developer"}'