Image Editor API

REST API reference for the Image Editor. For the product overview and UI walkthrough, see Image Editor.

The Image Editor is available via the Flokan public API, so you can run prompt-based image generation and edits from your own scripts, n8n flows, or any HTTP client. The API is synchronous: POST /process keeps the connection open until the provider returns the finished image.

Authentication

All requests require a workspace API key minted in Workspace Settings → API Keys. Pass the key in the Authorization header:

Authorization: Bearer flk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key must include the image_editor scope, and the user who created the key must have the Access Image Editor permission in the workspace.

Base URL

https://app.flokan.com/api/v1/image-editor

Choosing a source image

POST /process accepts three input modes — pick whichever fits your pipeline:

1. Text-to-image — omit both image_id and image_url. The prompt alone drives generation.
2. Edit a Flokan-hosted image — first call POST /upload-url, PUT the file to the returned upload_url, then pass the returned image_id to POST /process.
3. Edit an external image — pass image_url (HTTPS) directly. The server fetches the image and uses it as the source.

image_id takes precedence over image_url if both are sent.

Endpoints

POST /upload-url — Generate a presigned upload URL

Returns a short-lived PUT URL plus the image_id you'll pass to /process.

Request body

Response 201

{
  "success": true,
  "data": {
    "image_id": "f24a8c52-...",
    "upload_url": "https://...presigned PUT URL...",
    "public_url": "https://images.flokan.com/...",
    "expires_in": 3600
  }
}

PUT the file bytes to upload_url with the same Content-Type you declared as mime_type. The presigned URL expires after expires_in seconds (one hour).

POST /process — Generate or edit an image (synchronous)

The call returns once generation finishes (typically 10–60 seconds depending on model and provider). The Vercel max duration is 300 seconds.

Request body

BYOK + model tier compatibility

When provider is set to a BYOK provider, only certain model_tier values are accepted:

Passing an unsupported combination returns 400.

Response 201

{
  "success": true,
  "data": {
    "job_id": "9c0d4f31-...",
    "status": "completed",
    "result_url": "https://images.flokan.com/USER_ID/processed/JOB_ID.png",
    "result_image_id": "ab7e2511-...",
    "model_tier": "pro",
    "provider_used": "system",
    "credits_consumed": 50,
    "processing_ms": 18432,
    "created_at": "2026-05-04T11:00:00.000Z",
    "completed_at": "2026-05-04T11:00:18.432Z"
  }
}

result_image_id can be passed back as image_id on a follow-up /process call to chain edits — useful for iterative refinement workflows. provider_used is "system" for platform calls and the BYOK provider name otherwise. credits_consumed is 0 for BYOK calls.

POST /estimate-credits — Predict cost before calling /process

Returns a per-call upper-bound estimate plus the workspace's available credits and a can_proceed flag. Mirrors the BYOK rules of /process, so the estimate doesn't lie when you switch providers.

Request body

Response 200

{
  "success": true,
  "data": {
    "model_tier": "pro",
    "provider": "platform",
    "estimated_credits": 50,
    "is_exact": false,
    "available_credits": 12450,
    "can_proceed": true,
    "byok_skips_credits": false
  }
}

The estimate is an upper bound — the post-call deduction (visible on /process's response and on the job row) is the source of truth. BYOK providers always return estimated_credits: 0 and byok_skips_credits: true.

GET /jobs — List jobs

Query params

Returns the most recent jobs first.

GET /jobs/:jobId — Fetch one job

Returns the job's full row, including result_url, processing_ms, error (when failed), and the resolved style_id / image_id. Useful for historical lookups even though /process itself is synchronous.

Errors

All error responses use the envelope { "success": false, "error": "..." }. Common status codes:

Rate limits

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. The per-minute limit is determined by the workspace's billing plan.