API Documentation

Request Body

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" }

A 6-digit one-time code is emailed to you. Codes expire after 24 hours.

Request Body

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" }

Your API key (ak_...) is provided once at registration. Store it securely — it cannot be retrieved later. You can regenerate a new key from the Dashboard at any time.

List all tools available to your account. Each tool has a slug used in the process endpoint.

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": [ ... ]
  },
  {
    "id": 3,
    "slug": "logo-digitalize",
    "name": "Logo Digitalize",
    "description": "Multi-step logo pipeline",
    "endpoint": "/api/pipeline/logo-digitalize",
    "method": "POST",
    "type": "pipeline",
    "params": []
  }
]

The list includes both individual tools (type: "workflow") and admin-configured pipelines (type: "pipeline"). Use the endpoint field to determine the correct URL to call.

accepted_inputs lists which input types the tool understands (e.g. image, text, video, audio). required_inputs is the subset of those that are mandatory — anything in accepted_inputs but not in required_inputs is optional.

Run a tool. Accepts multipart/form-data. The response type depends on the tool — image, video, or JSON text (check output_types in the tool list).

Parameters

Response types

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

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

curl -X POST https://apiai.me/api/process/generate-video \
  -H "X-API-Key: ak_xxxx" \
  -F "prompt=aerial view of a coral reef" \
  -F "ASPECT_RATIO=16:9" \
  -F "DURATION=4" \
  --output result.mp4

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

Streaming progress (long-running tools)

For Replicate-backed tools that can take minutes (video generation, complex image models), append /stream to get real-time progress updates as a Server-Sent Events (SSE) stream. When the job finishes, pick up the result from GET /api/result/:id using the result_id in the final event.

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

# 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

Results are stored for 10 minutes and can only be retrieved once. Streaming requires the tool to be a Replicate workflow; other server types should use the synchronous endpoint.

Check supports_prompt and output_types in the tool list to know what each tool expects and returns.

Response headers:

Execute a multi-step pipeline. Pipelines chain multiple tools together — the output of each step feeds into the next.

Parameters

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

Create a new batch job. Upload multiple images and specify a workflow slug (or flow:slug for a user pipeline). All images will be processed with the same workflow/pipeline and parameters.

Parameters

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"

Response: 201 Created with job ID, status, total items, and estimated cost.

List your batch jobs (most recent first, max 50).

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

Get batch job status and all item details.

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

Cancel a running batch job. Items already completed are kept; remaining items are skipped.

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

Download all completed results as a ZIP archive. Available for 24 hours after job completion.

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

Get aggregated usage statistics for your account.

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

Retrieve recent request logs for your account.

Query Parameters

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

Server-Sent Events stream. Pushes real-time updates (new logs, usage changes) to connected clients. Authentication is via the X-API-Key header.

Note: the browser EventSource API does not support custom headers. Use fetch() with a readable stream, or pass the key via a proxy.

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));
}

Returns your current account balance.

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

{ "balance": 47.50 }

Create a Stripe Checkout session to top up your balance ($10, $50, or $100). Returns a URL to redirect to for payment. Your card is saved for future auto-refill charges.

Body Parameters (JSON)

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/..." }

Get your auto-refill settings. When enabled, your saved card is charged automatically when your balance drops below $5.

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

Enable or disable auto-refill. Requires a saved payment method (make at least one Stripe checkout payment first).

Body Parameters (JSON)

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}'

List your custom pipelines (user-created tool chains).

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

Create a custom pipeline by chaining existing tools. You must have access to all referenced tools. Optionally provide a flow_config for node-based pipelines with clean parameter names.

Request Body

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"
    }
  }'

Run a custom pipeline. Data passes through each step sequentially. For node-based pipelines, use the clean parameter names shown in /flows. For legacy pipelines, parameters are step-suffixed (e.g. prompt_1).

Pipelines may include gate nodes that validate content before proceeding. If a gate rejects the input, the pipeline stops early and returns 422 Unprocessable Entity with an error message explaining why. Gates can expose a named input parameter (e.g. check_image) so the API caller can provide content specifically for the gate to evaluate.

If an exposed image input supports multiple uploads (for example a first step backed by a workflow with max_images > 1), repeat that same multipart field name multiple times in one request.

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

Quality gates are special pipeline nodes that evaluate content (image, text, or both) against a custom prompt and return a YES or NO decision. They are powered by a fast AI model (~$0.001 per evaluation) and enable automated content moderation, quality control, and conditional routing inside pipelines.

How it works

A gate node receives the output from the previous step (image and/or text) and evaluates it against the gate prompt — a plain-language question like "Is this image safe for all audiences?" or "Does the product appear clearly?". The AI responds YES or NO.

Branching

Each branch (YES / NO) can be configured to:

Response behaviour

When a gate stops the pipeline:

When a gate continues (next or branch), the previous image and text are forwarded to the target node automatically.

Custom messages

Each branch can define a custom message returned when the pipeline stops at that branch. If no message is set, defaults are used ("Content did not pass quality gate" for NO, "Pipeline completed" for YES).

Use cases

• Content moderation — block unsafe, off-brand, or policy-violating outputs before delivery
• Quality control — reject blurry, cropped, or low-quality generated images
• Conditional routing — send YES results to one processing path and NO results to another
• Approval workflows — gate on subjective criteria like brand consistency or style match

Ask any YES/NO question about an image and/or text. A general-purpose evaluation endpoint powered by fast AI (~$0.001 per call). Use for content moderation, quality checks, object detection, classification, and more. This is the standalone version of the Quality Gate node used inside pipelines.

Request

Send as multipart/form-data:

* At least one of image, image_base64, or text is required alongside the prompt.

Response (200 OK)

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

Response fields

Example prompts

curl examples

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"

Evaluate an image against a configurable policy and receive a structured JSON decision. Always returns 200 for successful checks — the decision (allow, reject, or review) is in the response body, not the HTTP status code. Powered by a fast AI model (~$0.001 per check).

Request

Send as multipart/form-data:

* Provide either image or image_base64, not both.

Built-in policies

Pass one of these slugs as policy and omit policy_prompt to use the pre-built moderation instructions. You can override any preset by supplying your own policy_prompt.

For domain-specific checks (e.g. "does this image contain our product logo?") use a custom policy label and supply policy_prompt with your own instructions.

Response (200 OK)

{
  "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
}

Decision values

HTTP status codes

Error responses (non-200)

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

Response headers

curl examples

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"

Pipeline integration

This endpoint uses the same evaluation engine as Quality Gates in pipelines. When a gate node is used inside a pipeline, downstream condition nodes can branch on decision, confidence, and reasons[].code from the structured moderation result.

Delete a custom pipeline by its ID.

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

The server uses the Streamable HTTP transport. Authenticate with your API key via the X-API-Key header.

VS Code — .vscode/mcp.json

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

Cursor — .cursor/mcp.json

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

Ollama — ~/.ollama/mcp.json

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

Available tools

Once connected, your AI assistant has access to these tools:

Example prompts

"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"