API Documentation

N1FILTER AI API allows you to generate AI-powered images and videos programmatically. Send an image, choose a preset, and get the result via a simple REST API.

Quick start:

Create an account and get your API key from the cabinet
Add the key to Authorization: Bearer YOUR_API_KEY header
Call GET /api/v1/generation/prices to see available presets
Send a generation request and poll for the result

Authentication

All API requests require an API key passed in the Authorization header as a Bearer token.

Authorization: Bearer sk-abc123def456-7890abcdef123456

You can create and manage API keys in your cabinet. Each account can have one active key at a time.

Don't have an API key yet?

Create Free Account

Base URL

https://n1-filter.digital/api/v1

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with a detail field.

Code	Meaning
`400`	Bad request — invalid parameters, unsupported image format, file too large
`401`	Unauthorized — missing or invalid API key
`402`	Insufficient balance — not enough tokens for this generation
`404`	Not found — order doesn't exist or belongs to another user
`410`	Gone — generation result has expired (24h TTL)
`500`	Internal server error

Error response example:

{
  "detail": "Unsupported image type: image/gif. Allowed: jpg, png, webp"
}

GET

/generation/balance

Returns the current token balance for the authenticated user.

Response

{
  "token_balance": 5000
}

Code Examples

import httpx

API_KEY = "sk-your-api-key"
BASE = "https://n1-filter.digital/api/v1"

resp = httpx.get(
    f"{BASE}/generation/balance",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
data = resp.json()
print(f"Balance: {data['token_balance']} tokens")

const API_KEY = "sk-your-api-key";
const BASE = "https://n1-filter.digital/api/v1";

const resp = await fetch(`${BASE}/generation/balance`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await resp.json();
console.log(`Balance: ${data.token_balance} tokens`);

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    apiKey := "sk-your-api-key"
    base := "https://n1-filter.digital/api/v1"

    req, _ := http.NewRequest("GET", base+"/generation/balance", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result struct {
        TokenBalance int `json:"token_balance"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Balance: %d tokens\n", result.TokenBalance)
}

GET

/generation/prices

Returns available generation presets and their prices in tokens.

Response

{
  "generation": {
    "image": {
      "presets": [
        { "id": "preset_1", "price": 100 },
        { "id": "preset_2", "price": 150 }
      ]
    },
    "video": {
      "presets": [
        { "id": "preset_v1", "price": 300 }
      ],
      "seconds_price": 50
    }
  }
}

Video pricing: total cost = preset.price + (seconds - 4) * seconds_price. Base duration is 4 seconds, max is 8.

Code Examples

import httpx

API_KEY = "sk-your-api-key"
BASE = "https://n1-filter.digital/api/v1"

resp = httpx.get(
    f"{BASE}/generation/prices",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
prices = resp.json()

for preset in prices["generation"]["image"]["presets"]:
    print(f"Image preset {preset['id']}: {preset['price']} tokens")

const API_KEY = "sk-your-api-key";
const BASE = "https://n1-filter.digital/api/v1";

const resp = await fetch(`${BASE}/generation/prices`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const prices = await resp.json();

for (const preset of prices.generation.image.presets) {
  console.log(`Image preset ${preset.id}: ${preset.price} tokens`);
}

req, _ := http.NewRequest("GET", base+"/generation/prices", nil)
req.Header.Set("Authorization", "Bearer "+apiKey)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var prices struct {
    Generation struct {
        Image struct {
            Presets []struct {
                ID    string `json:"id"`
                Price int    `json:"price"`
            } `json:"presets"`
        } `json:"image"`
    } `json:"generation"`
}
json.NewDecoder(resp.Body).Decode(&prices)

for _, p := range prices.Generation.Image.Presets {
    fmt.Printf("Image preset %s: %d tokens\n", p.ID, p.Price)
}

POST

/generation/image

Create an image generation. Send an image file and a preset ID. The cost is deducted from your balance immediately.

Request Body (multipart/form-data)

Field	Type	Required	Description
`image`	file	Yes	JPEG, PNG, or WebP. Max 5 MB.
`preset_id`	string	Yes	Preset ID from `/generation/prices`

Response

{
  "id": 42,
  "user_id": 1,
  "type": "image",
  "preset_id": "preset_1",
  "seconds": null,
  "status": "pending",
  "tokens_spent": 100,
  "tokens_refunded": false,
  "result": null,
  "error_msg": null,
  "created_at": 1711440000.0,
  "completed_at": null
}

Code Examples

import httpx

API_KEY = "sk-your-api-key"
BASE = "https://n1-filter.digital/api/v1"

with open("photo.jpg", "rb") as f:
    resp = httpx.post(
        f"{BASE}/generation/image",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"image": ("photo.jpg", f, "image/jpeg")},
        data={"preset_id": "preset_1"},
    )

order = resp.json()
print(f"Order #{order['id']} — status: {order['status']}")

import fs from "fs";

const API_KEY = "sk-your-api-key";
const BASE = "https://n1-filter.digital/api/v1";

const form = new FormData();
form.append("image", new Blob([fs.readFileSync("photo.jpg")]), "photo.jpg");
form.append("preset_id", "preset_1");

const resp = await fetch(`${BASE}/generation/image`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
});

const order = await resp.json();
console.log(`Order #${order.id} — status: ${order.status}`);

func generateImage(apiKey, base, presetID, imagePath string) {
    file, _ := os.Open(imagePath)
    defer file.Close()

    var body bytes.Buffer
    writer := multipart.NewWriter(&body)
    part, _ := writer.CreateFormFile("image", "photo.jpg")
    io.Copy(part, file)
    writer.WriteField("preset_id", presetID)
    writer.Close()

    req, _ := http.NewRequest("POST", base+"/generation/image", &body)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", writer.FormDataContentType())

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var order struct {
        ID     int    `json:"id"`
        Status string `json:"status"`
    }
    json.NewDecoder(resp.Body).Decode(&order)
    fmt.Printf("Order #%d — status: %s\n", order.ID, order.Status)
}

Want to try it yourself?

Try for Free

POST

/generation/video

Create a video generation. Same as image, but with an additional seconds parameter (4-8).

Request Body (multipart/form-data)

Field	Type	Required	Description
`image`	file	Yes	JPEG, PNG, or WebP. Max 5 MB.
`preset_id`	string	Yes	Preset ID from `/generation/prices`
`seconds`	integer	No	Video duration: 4-8 seconds. Default: 4.

Response

{
  "id": 43,
  "user_id": 1,
  "type": "video",
  "preset_id": "preset_v1",
  "seconds": 6,
  "status": "pending",
  "tokens_spent": 400,
  "tokens_refunded": false,
  "result": null,
  "error_msg": null,
  "created_at": 1711440060.0,
  "completed_at": null
}

Code Examples

import httpx

API_KEY = "sk-your-api-key"
BASE = "https://n1-filter.digital/api/v1"

with open("photo.jpg", "rb") as f:
    resp = httpx.post(
        f"{BASE}/generation/video",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"image": ("photo.jpg", f, "image/jpeg")},
        data={"preset_id": "preset_v1", "seconds": "6"},
    )

order = resp.json()
print(f"Video order #{order['id']} — {order['seconds']}s")

import fs from "fs";

const API_KEY = "sk-your-api-key";
const BASE = "https://n1-filter.digital/api/v1";

const form = new FormData();
form.append("image", new Blob([fs.readFileSync("photo.jpg")]), "photo.jpg");
form.append("preset_id", "preset_v1");
form.append("seconds", "6");

const resp = await fetch(`${BASE}/generation/video`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
});

const order = await resp.json();
console.log(`Video order #${order.id} — ${order.seconds}s`);

func generateVideo(apiKey, base, presetID, imagePath string, seconds int) {
    file, _ := os.Open(imagePath)
    defer file.Close()

    var body bytes.Buffer
    writer := multipart.NewWriter(&body)
    part, _ := writer.CreateFormFile("image", "photo.jpg")
    io.Copy(part, file)
    writer.WriteField("preset_id", presetID)
    writer.WriteField("seconds", fmt.Sprintf("%d", seconds))
    writer.Close()

    req, _ := http.NewRequest("POST", base+"/generation/video", &body)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", writer.FormDataContentType())

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var order struct {
        ID      int `json:"id"`
        Seconds int `json:"seconds"`
    }
    json.NewDecoder(resp.Body).Decode(&order)
    fmt.Printf("Video order #%d — %ds\n", order.ID, order.Seconds)
}

GET

/generation/orders

List your generation orders. Supports pagination.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	50	Max items to return (1-100)
`offset`	integer	0	Number of items to skip

Response

[
  {
    "id": 42,
    "user_id": 1,
    "type": "image",
    "preset_id": "preset_1",
    "seconds": null,
    "status": "completed",
    "tokens_spent": 100,
    "tokens_refunded": false,
    "result": "a1b2c3d4.jpg",
    "error_msg": null,
    "created_at": 1711440000.0,
    "completed_at": 1711440120.0
  }
]

Code Examples

resp = httpx.get(
    f"{BASE}/generation/orders",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 10, "offset": 0},
)
orders = resp.json()

for order in orders:
    print(f"#{order['id']} [{order['status']}] — {order['tokens_spent']} tokens")

const resp = await fetch(`${BASE}/generation/orders?limit=10&offset=0`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const orders = await resp.json();

for (const order of orders) {
  console.log(`#${order.id} [${order.status}] — ${order.tokens_spent} tokens`);
}

req, _ := http.NewRequest("GET", base+"/generation/orders?limit=10&offset=0", nil)
req.Header.Set("Authorization", "Bearer "+apiKey)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var orders []struct {
    ID          int    `json:"id"`
    Status      string `json:"status"`
    TokensSpent int    `json:"tokens_spent"`
}
json.NewDecoder(resp.Body).Decode(&orders)

for _, o := range orders {
    fmt.Printf("#%d [%s] — %d tokens\n", o.ID, o.Status, o.TokensSpent)
}

GET

/generation/orders/{order_id}

Check the status of a specific order. Use this to poll until the generation is complete.

Order Statuses

Status	Description
`pending`	Order created, waiting to be processed
`processing`	Generation is in progress
`completed`	Done! Result is ready for download
`failed`	Generation failed. Check `error_msg`. Tokens are refunded automatically.
`canceled`	Order was canceled. Tokens are refunded.

Response

{
  "id": 42,
  "user_id": 1,
  "type": "image",
  "preset_id": "preset_1",
  "seconds": null,
  "status": "completed",
  "tokens_spent": 100,
  "tokens_refunded": false,
  "result": "a1b2c3d4.jpg",
  "error_msg": null,
  "created_at": 1711440000.0,
  "completed_at": 1711440120.0
}

Code Examples

import time

order_id = 42

while True:
    resp = httpx.get(
        f"{BASE}/generation/orders/{order_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    order = resp.json()
    print(f"Status: {order['status']}")

    if order["status"] in ("completed", "failed", "canceled"):
        break

    time.sleep(3)

const orderId = 42;

while (true) {
  const resp = await fetch(`${BASE}/generation/orders/${orderId}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const order = await resp.json();
  console.log(`Status: ${order.status}`);

  if (["completed", "failed", "canceled"].includes(order.status)) break;

  await new Promise((r) => setTimeout(r, 3000));
}

orderID := 42

for {
    url := fmt.Sprintf("%s/generation/orders/%d", base, orderID)
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, _ := http.DefaultClient.Do(req)

    var order struct {
        Status string `json:"status"`
    }
    json.NewDecoder(resp.Body).Decode(&order)
    resp.Body.Close()

    fmt.Printf("Status: %s\n", order.Status)

    if order.Status == "completed" || order.Status == "failed" || order.Status == "canceled" {
        break
    }
    time.Sleep(3 * time.Second)
}

GET

/generation/orders/{order_id}/download

Download the generated file. Only available for orders with status: "completed". Results expire after 24 hours.

Response: Binary file (image/jpeg, image/png, image/webp, video/mp4, video/webm) with Content-Disposition header.

Code Examples

order_id = 42

resp = httpx.get(
    f"{BASE}/generation/orders/{order_id}/download",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if resp.status_code == 200:
    filename = f"result_{order_id}.jpg"
    with open(filename, "wb") as f:
        f.write(resp.content)
    print(f"Saved to {filename}")
elif resp.status_code == 410:
    print("Result expired (24h TTL)")

import fs from "fs";

const orderId = 42;

const resp = await fetch(`${BASE}/generation/orders/${orderId}/download`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (resp.ok) {
  const buffer = Buffer.from(await resp.arrayBuffer());
  fs.writeFileSync(`result_${orderId}.jpg`, buffer);
  console.log("Saved!");
} else if (resp.status === 410) {
  console.log("Result expired (24h TTL)");
}

orderID := 42
url := fmt.Sprintf("%s/generation/orders/%d/download", base, orderID)
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "Bearer "+apiKey)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

if resp.StatusCode == 200 {
    filename := fmt.Sprintf("result_%d.jpg", orderID)
    out, _ := os.Create(filename)
    io.Copy(out, resp.Body)
    out.Close()
    fmt.Printf("Saved to %s\n", filename)
} else if resp.StatusCode == 410 {
    fmt.Println("Result expired (24h TTL)")
}

Full Integration Flow

Complete example: check balance, create a generation, poll for status, and download the result.

import httpx
import time

API_KEY = "sk-your-api-key"
BASE = "https://n1-filter.digital/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Check balance
balance = httpx.get(f"{BASE}/generation/balance", headers=headers).json()
print(f"Balance: {balance['token_balance']} tokens")

# 2. Get available presets
prices = httpx.get(f"{BASE}/generation/prices", headers=headers).json()
preset_id = prices["generation"]["image"]["presets"][0]["id"]
price = prices["generation"]["image"]["presets"][0]["price"]
print(f"Using preset '{preset_id}' — {price} tokens")

if balance["token_balance"] < price:
    print("Not enough tokens!")
    exit(1)

# 3. Create generation
with open("photo.jpg", "rb") as f:
    resp = httpx.post(
        f"{BASE}/generation/image",
        headers=headers,
        files={"image": ("photo.jpg", f, "image/jpeg")},
        data={"preset_id": preset_id},
    )
order = resp.json()
order_id = order["id"]
print(f"Order #{order_id} created")

# 4. Poll for completion
while True:
    status = httpx.get(
        f"{BASE}/generation/orders/{order_id}",
        headers=headers,
    ).json()

    print(f"  Status: {status['status']}")

    if status["status"] == "completed":
        break
    elif status["status"] in ("failed", "canceled"):
        print(f"  Error: {status.get('error_msg', 'unknown')}")
        exit(1)

    time.sleep(3)

# 5. Download result
resp = httpx.get(
    f"{BASE}/generation/orders/{order_id}/download",
    headers=headers,
)
with open(f"result_{order_id}.jpg", "wb") as f:
    f.write(resp.content)
print(f"Done! Saved to result_{order_id}.jpg")

import fs from "fs";

const API_KEY = "sk-your-api-key";
const BASE = "https://n1-filter.digital/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}` };

// 1. Check balance
const balance = await (await fetch(`${BASE}/generation/balance`, { headers })).json();
console.log(`Balance: ${balance.token_balance} tokens`);

// 2. Get available presets
const prices = await (await fetch(`${BASE}/generation/prices`, { headers })).json();
const preset = prices.generation.image.presets[0];
console.log(`Using preset '${preset.id}' — ${preset.price} tokens`);

if (balance.token_balance < preset.price) {
  console.log("Not enough tokens!");
  process.exit(1);
}

// 3. Create generation
const form = new FormData();
form.append("image", new Blob([fs.readFileSync("photo.jpg")]), "photo.jpg");
form.append("preset_id", preset.id);

const order = await (
  await fetch(`${BASE}/generation/image`, {
    method: "POST",
    headers,
    body: form,
  })
).json();
console.log(`Order #${order.id} created`);

// 4. Poll for completion
while (true) {
  const status = await (
    await fetch(`${BASE}/generation/orders/${order.id}`, { headers })
  ).json();

  console.log(`  Status: ${status.status}`);

  if (status.status === "completed") break;
  if (["failed", "canceled"].includes(status.status)) {
    console.log(`  Error: ${status.error_msg || "unknown"}`);
    process.exit(1);
  }

  await new Promise((r) => setTimeout(r, 3000));
}

// 5. Download result
const result = await fetch(
  `${BASE}/generation/orders/${order.id}/download`,
  { headers }
);
fs.writeFileSync(
  `result_${order.id}.jpg`,
  Buffer.from(await result.arrayBuffer())
);
console.log(`Done! Saved to result_${order.id}.jpg`);

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
    "time"
)

const (
    apiKey = "sk-your-api-key"
    base   = "https://n1-filter.digital/api/v1"
)

func doGet(url string, target interface{}) {
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    json.NewDecoder(resp.Body).Decode(target)
}

func main() {
    // 1. Check balance
    var balance struct{ TokenBalance int `json:"token_balance"` }
    doGet(base+"/generation/balance", &balance)
    fmt.Printf("Balance: %d tokens\n", balance.TokenBalance)

    // 2. Get presets
    var prices struct {
        Generation struct {
            Image struct {
                Presets []struct {
                    ID    string `json:"id"`
                    Price int    `json:"price"`
                } `json:"presets"`
            } `json:"image"`
        } `json:"generation"`
    }
    doGet(base+"/generation/prices", &prices)
    preset := prices.Generation.Image.Presets[0]
    fmt.Printf("Using preset '%s' — %d tokens\n", preset.ID, preset.Price)

    // 3. Create generation
    file, _ := os.Open("photo.jpg")
    defer file.Close()
    var body bytes.Buffer
    writer := multipart.NewWriter(&body)
    part, _ := writer.CreateFormFile("image", "photo.jpg")
    io.Copy(part, file)
    writer.WriteField("preset_id", preset.ID)
    writer.Close()

    req, _ := http.NewRequest("POST", base+"/generation/image", &body)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    resp, _ := http.DefaultClient.Do(req)

    var order struct {
        ID     int    `json:"id"`
        Status string `json:"status"`
    }
    json.NewDecoder(resp.Body).Decode(&order)
    resp.Body.Close()
    fmt.Printf("Order #%d created\n", order.ID)

    // 4. Poll for completion
    for {
        var status struct {
            Status   string `json:"status"`
            ErrorMsg string `json:"error_msg"`
        }
        doGet(fmt.Sprintf("%s/generation/orders/%d", base, order.ID), &status)
        fmt.Printf("  Status: %s\n", status.Status)

        if status.Status == "completed" {
            break
        }
        if status.Status == "failed" || status.Status == "canceled" {
            fmt.Printf("  Error: %s\n", status.ErrorMsg)
            return
        }
        time.Sleep(3 * time.Second)
    }

    // 5. Download result
    dlReq, _ := http.NewRequest("GET",
        fmt.Sprintf("%s/generation/orders/%d/download", base, order.ID), nil)
    dlReq.Header.Set("Authorization", "Bearer "+apiKey)
    dlResp, _ := http.DefaultClient.Do(dlReq)
    defer dlResp.Body.Close()

    filename := fmt.Sprintf("result_%d.jpg", order.ID)
    out, _ := os.Create(filename)
    io.Copy(out, dlResp.Body)
    out.Close()
    fmt.Printf("Done! Saved to %s\n", filename)
}