Tài liệu API

Nordic Layers là một REST API qua HTTPS tại https://app.layers.nordicbyte.co.uk. Dự án là một tài liệu JSON gồm các lớp; bạn thay đổi nó bằng các thao tác và xuất thành ảnh. Trình chỉnh sửa trên trình duyệt dùng cùng API này.

Xác thực

Tạo khóa API trong bảng điều khiển tài khoản và gửi kèm mọi yêu cầu /v1. Khóa bắt đầu bằng nl_key_.

Authorization: Bearer nl_key_…

Quy trình thông thường

Tải lên từng ảnh bằng POST /v1/assets, với tệp là nội dung thô của yêu cầu (PNG, JPEG, WebP, GIF, BMP hoặc TIFF). Phản hồi có id của ảnh.
Tạo dự án bằng POST /v1/projects với width, height và background. Bạn có thể truyền luôn các steps đầu tiên trong cùng lệnh gọi.
Chỉnh sửa bằng POST /v1/projects/{id}/run: một thao tác dạng {"op": …} hoặc nhiều thao tác dạng {"steps": [...]}. Xem kết quả bằng GET /v1/projects/{id}/preview, miễn phí.
Xuất bằng POST /v1/projects/{id}/export. Phản hồi chứa URL của tệp, hoặc chính bức ảnh nếu dùng "response": "image".

Yêu cầu đầu tiên

Tạo dự án 1080×1080 có chuyển sắc và tiêu đề, rồi xuất sang WebP:

curl -X POST https://app.layers.nordicbyte.co.uk/v1/projects \
  -H "Authorization: Bearer $NL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "First post",
    "width": 1080,
    "height": 1080,
    "steps": [
      {"op": "layer.addFill", "gradient": {"colors": ["#1E3A5F", "#64B5F6"], "angle": 135}},
      {"op": "text.add", "content": "Hello, layers", "fontName": "Segoe UI", "fontSize": 110, "bold": true, "color": "#FFFFFF"},
      {"op": "effects.set", "shadow": {"opacity": 0.4, "distance": 12, "size": 24}}
    ]
  }'

# → {"project": {"id": "…", …}}

curl -X POST https://app.layers.nordicbyte.co.uk/v1/projects/$PROJECT_ID/export \
  -H "Authorization: Bearer $NL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "webp",
    "quality": 90
  }'

Endpoint

Phương thức	Đường dẫn	Chức năng
`GET`	`/health`	Trạng thái dịch vụ
`GET`	`/v1/ops`	Danh mục mọi thao tác và tham số của chúng (công khai)
`POST`	`/v1/assets?name=photo.jpg`	Tải ảnh lên; nội dung yêu cầu là tệp
`GET`	`/v1/assets`	Liệt kê ảnh của bạn và cho biết dự án nào đang dùng chúng
`DELETE`	`/v1/assets/{id}`	Xóa một ảnh
`POST`	`/v1/projects`	Tạo dự án (khung vẽ, hoặc cả tài liệu, kèm các bước tùy chọn)
`GET`	`/v1/projects`	Liệt kê dự án của bạn
`GET`	`/v1/projects/{id}`	Một dự án cùng tài liệu của nó
`PUT`	`/v1/projects/{id}/document`	Thay thế toàn bộ tài liệu
`POST`	`/v1/projects/{id}/run`	Áp dụng một thao tác hoặc một danh sách bước
`POST`	`/v1/projects/{id}/undo`	Hoàn tác thay đổi gần nhất
`POST`	`/v1/projects/{id}/redo`	Làm lại
`GET`	`/v1/projects/{id}/preview?size=1024`	Xem trước PNG miễn phí, cạnh dài tối đa `size` px
`POST`	`/v1/projects/{id}/export`	Xuất PNG, JPEG hoặc WebP; có thể kèm các bước chỉ áp dụng cho tệp này
`POST`	`/v1/render`	Kết xuất không lưu trạng thái cho cả tài liệu
`GET`	`/v1/exports`	Liệt kê các bản xuất của bạn
`GET`	`/v1/exports/{id}/file`	Tải một bản xuất
`DELETE`	`/v1/projects/{id}`	Xóa một dự án

Thao tác

Mỗi thao tác là một đối tượng có op và các tham số của nó. Lớp được tham chiếu bằng id hoặc tên; nếu không có layer, lớp đang chọn sẽ được dùng. Tên không phân biệt hoa thường và khoảng trắng, nên "Linear Dodge (Add)" và "linearDodge" là cùng một chế độ hòa trộn. Với steps, các bước chạy theo thứ tự và dừng ở lỗi đầu tiên (trừ khi đặt "stopOnError": false); các bước trước đó vẫn được giữ nguyên.

Lớp
Văn bản
Hình
Biến đổi
Điều chỉnh trên một lớp
Bộ lọc
Lớp điều chỉnh
Mặt nạ lớp
Hiệu ứng lớp
Khung vẽ
Dự án

Lớp

Thao tác	Tham số	Chức năng
`layer.add`	`color, name`	Alias of layer.addFill (the web has no empty pixel layers).
`layer.addFill`	`color \| gradient {colors: [..], angle, type: linear\|radial}, name, above, atBottom`	A colour or gradient layer the size of the canvas.
`layer.addImage`	`asset_id \| color, name, rect \| origin \| center, width, height, fit (stretch\|contain\|cover), fitCanvas (contain\|cover), above, atBottom, opacity, blendMode`	Add an uploaded image (asset_id) or a solid colour (color).
`layer.clip`	`layer`	Clip a layer to the one below it (clipping mask).
`layer.delete`	`layer \| layers`	Delete layers.
`layer.duplicate`	`layer, name`	Copy a layer above itself.
`layer.get`	`layer`	One layer with all its settings.
`layer.list`	—	Layers from bottom to top.
`layer.move`	`layer, above \| below (layer), toTop, atBottom, index, offset`	Reorder a layer.
`layer.rename`	`layer, name`	Rename a layer.
`layer.select`	`layer`	Make a layer the active one.
`layer.setBlendMode`	`layer \| layers, blendMode (normal, darken, multiply, colorBurn, linearBurn, lighten, screen, colorDodge, linearDodge, overlay, softLight, hardLight, difference, exclusion, subtract, divide, hue, saturation, color, luminosity)`	Blend mode.
`layer.setFill`	`layer, color \| gradient`	Change a fill layer's colour or gradient.
`layer.setImage`	`layer, asset_id, fit (stretch\|contain\|cover)`	Replace a layer's image and keep its box (templates).
`layer.setOpacity`	`layer \| layers, opacity`	Layer opacity, 0 to 1.
`layer.setVisible`	`layer \| layers, visible`	Show or hide layers.
`layer.unclip`	`layer`	Release a clipping mask.

Văn bản

Thao tác	Tham số	Chức năng
`text.add`	`content, fontName, fontSize, color, alignment, leading, bold, italic, boxWidth, origin \| center, name`	Add a text layer.
`text.defaults`	—	Fonts on the server and whether complex scripts are shaped.
`text.set`	`layer, content, fontName, fontSize, color, alignment, leading, bold, italic, boxWidth`	Change a text layer.

Hình

Thao tác	Tham số	Chức năng
`shape.add`	`shape, rect \| from+to, color, cornerRadius, lineWidth, name`	Add a rectangle, ellipse or line.
`shape.set`	`layer, color, cornerRadius, lineWidth`	Change a shape layer.

Biến đổi

Thao tác	Tham số	Chức năng
`transform.flip`	`layer \| layers, axis (horizontal\|vertical)`	Flip horizontally or vertically.
`transform.move`	`layer \| layers, dx, dy \| to [x, y]`	Move by dx/dy or to a point.
`transform.rotate`	`layer \| layers, angle`	Rotate by an angle (degrees, clockwise).
`transform.scale`	`layer \| layers, factor \| percent \| width \| height`	Scale around each layer's centre.
`transform.set`	`layer \| layers, x, y, width, height, rotation, flipX, flipY`	Box, rotation and flips.

Điều chỉnh trên một lớp

Thao tác	Tham số	Chức năng
`adjust.blackWhite`	`layer \| layers, reds, yellows, greens, cyans, blues, magentas, tint, tintHue, tintSaturation`	Non-destructive blackWhite on a layer (adds it or updates it).
`adjust.brightnessContrast`	`layer \| layers, brightness, contrast`	Non-destructive brightnessContrast on a layer (adds it or updates it).
`adjust.clear`	`layer \| layers`	Remove every adjustment and filter from a layer.
`adjust.colorBalance`	`layer \| layers, shadows, midtones, highlights, preserveLuminosity`	Non-destructive colorBalance on a layer (adds it or updates it).
`adjust.curves`	`layer \| layers, rgb, red, green, blue`	Non-destructive curves on a layer (adds it or updates it).
`adjust.exposure`	`layer \| layers, exposure, offset, gamma`	Non-destructive exposure on a layer (adds it or updates it).
`adjust.gradientMap`	`layer \| layers, shadows, highlights, reversed`	Non-destructive gradientMap on a layer (adds it or updates it).
`adjust.grain`	`layer \| layers, amount, size, seed`	Non-destructive grain on a layer (adds it or updates it).
`adjust.hueSaturation`	`layer \| layers, hue, saturation, lightness, colorize`	Non-destructive hueSaturation on a layer (adds it or updates it).
`adjust.invert`	`layer \| layers, no settings`	Non-destructive invert on a layer (adds it or updates it).
`adjust.levels`	`layer \| layers, black, white, gamma, outputBlack, outputWhite`	Non-destructive levels on a layer (adds it or updates it).
`adjust.remove`	`layer \| layers, kind`	Remove one adjustment or filter from a layer.

Bộ lọc

Thao tác	Tham số	Chức năng
`filter.addNoise`	`layer \| layers, amount, gaussian, monochromatic, seed`	Non-destructive addNoise on a layer (adds it or updates it).
`filter.gaussianBlur`	`layer \| layers, radius`	Non-destructive gaussianBlur on a layer (adds it or updates it).
`filter.motionBlur`	`layer \| layers, angle, distance`	Non-destructive motionBlur on a layer (adds it or updates it).
`filter.pixelate`	`layer \| layers, size`	Non-destructive pixelate on a layer (adds it or updates it).
`filter.sharpen`	`layer \| layers, amount, radius, threshold`	Non-destructive sharpen on a layer (adds it or updates it).
`filter.vignette`	`layer \| layers, amount, midpoint, roundness, feather, color`	Non-destructive vignette on a layer (adds it or updates it).

Lớp điều chỉnh

Thao tác	Tham số	Chức năng
`adjustmentLayer.add`	`kind, settings…, name, above`	An adjustment layer: changes everything below it.
`adjustmentLayer.get`	`layer`	An adjustment layer's settings.
`adjustmentLayer.set`	`layer, settings…`	Change an adjustment layer (partial).

Mặt nạ lớp

Thao tác	Tham số	Chức năng
`mask.add`	`layer, reveal \| hide \| rect \| ellipse (rect) \| gradient (from, to) \| asset_id (+ rect), feather, invert, cornerRadius`	Add or replace a layer mask.
`mask.blur`	`layer, radius`	Feather the layer mask.
`mask.delete`	`layer`	Remove the layer mask.
`mask.invert`	`layer`	Invert the layer mask.
`mask.setEnabled`	`layer, enabled`	Turn the layer mask on or off.

Hiệu ứng lớp

Thao tác	Tham số	Chức năng
`effects.copy`	`from, layer \| layers`	Copy effects from one layer to others.
`effects.get`	`layer`	A layer's effects.
`effects.remove`	`layer \| layers, kinds`	Remove effects (all, or the ones named).
`effects.set`	`layer \| layers, shadow {…}, stroke {…}, outerGlow {…}, colorOverlay {…}`	Set effects (partial): shadow, outerGlow, stroke, colorOverlay.
`effects.setEnabled`	`layer, kind, enabled`	Turn one effect on or off.

Khung vẽ

Thao tác	Tham số	Chức năng
`canvas.crop`	`rect [x, y, width, height]`	Crop the canvas to a rectangle.
`canvas.imageSize`	`width and/or height, or percent`	Scale the whole document.
`canvas.setBackground`	`color`	Background colour, or null for transparent.
`canvas.size`	`width, height, anchor (topLeft…bottomRight, default center)`	Change the canvas without scaling layers.

Dự án

Thao tác	Tham số	Chức năng
`project.state`	—	The whole document.

Chế độ hòa trộn

normal
darken
multiply
colorBurn
linearBurn
lighten
screen
colorDodge
linearDodge
overlay
softLight
hardLight
difference
exclusion
subtract
divide
hue
saturation
color
luminosity

Họ phông chữ

Arial
Segoe UI
Calibri
Verdana
Tahoma
Trebuchet MS
Georgia
Times New Roman
Courier New
Consolas
Impact
Comic Sans MS

Mẫu

Truyền steps vào lệnh xuất và chúng sẽ được áp dụng lên một bản sao của dự án, chỉ cho tệp đó. Một mẫu, nhiều tệp: đổi văn bản bằng text.set và ảnh bằng layer.setImage, giữ nguyên khung của lớp.

curl -X POST https://app.layers.nordicbyte.co.uk/v1/projects/$TEMPLATE_ID/export \
  -H "Authorization: Bearer $NL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "steps": [
      {"op": "text.set", "layer": "Title", "content": "Nueva colección"},
      {"op": "layer.setImage", "layer": "Photo", "asset_id": "photo_dunes"}
    ]
  }'

Kết xuất không lưu trạng thái

POST /v1/render nhận một document đầy đủ (như được trả về trong project.document), các steps tùy chọn và tùy chọn xuất, và không lưu dự án. Với "response": "image", phản hồi là tệp ảnh.

curl -X POST https://app.layers.nordicbyte.co.uk/v1/render \
  -H "Authorization: Bearer $NL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {"width": 1200, "height": 630, "background": "#1E3A5F", "layers": ["…"]},
    "format": "png",
    "response": "image"
  }' \
  -o card.png

Lỗi

Lỗi được trả về dưới dạng JSON với code ổn định và thông báo detail bằng ngôn ngữ của tài khoản bạn. Một bước thất bại sẽ cho biết tham số nào sai. Khi hết lượt kết xuất của gói, API trả về 402 kèm quota_renders.

Giới hạn

Tải lên tối đa 50 MB và 12,000 px mỗi cạnh.
Khung vẽ tối đa 20,000 px mỗi cạnh, trong giới hạn megapixel của gói.
Tối đa 200 bước mỗi lệnh gọi.
Bản xem trước tối đa 2,048 px ở cạnh dài.
Megapixel, lớp, dự án, dung lượng lưu trữ và số lượt kết xuất mỗi tháng phụ thuộc vào gói: xem Bảng giá.