توثيق الـ API

Nordic Layers واجهة REST API عبر HTTPS على https://app.layers.nordicbyte.co.uk. المشروع مستند JSON من الطبقات؛ تغيّره بالعمليات وتصدّره صورة. محرر المتصفح يستخدم الـ API نفسه.

المصادقة

أنشئ مفتاح API في لوحة حسابك وأرسله مع كل طلب إلى /v1. تبدأ المفاتيح بـ nl_key_.

Authorization: Bearer nl_key_…

التدفق المعتاد

ارفع كل صورة بـ POST /v1/assets والملف جسمًا خامًا للطلب (PNG أو JPEG أو WebP أو GIF أو BMP أو TIFF). تحمل الاستجابة قيمة id الخاصة بها.
أنشئ مشروعًا بـ POST /v1/projects مع width وheight وbackground. يمكنك تمرير أول steps في الاستدعاء نفسه.
عدّله بـ POST /v1/projects/{id}/run: عملية واحدة بصيغة {"op": …} أو عدة عمليات بصيغة {"steps": [...]}. شاهده بـ GET /v1/projects/{id}/preview، وهو مجاني.
صدّر بـ POST /v1/projects/{id}/export. تحمل الاستجابة رابط الملف، أو الصورة نفسها مع "response": "image".

أول طلب

أنشئ مشروعًا 1080×1080 بتدرج وعنوان، ثم صدّره بصيغة 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
  }'

نقاط النهاية

الطريقة	المسار	ما تفعله
`GET`	`/health`	حالة الخدمة
`GET`	`/v1/ops`	كتالوج كل العمليات ومعاملاتها (علني)
`POST`	`/v1/assets?name=photo.jpg`	رفع صورة؛ الجسم هو الملف
`GET`	`/v1/assets`	سرد صورك ومعرفة هل يستخدمها مشروع
`DELETE`	`/v1/assets/{id}`	حذف صورة
`POST`	`/v1/projects`	إنشاء مشروع (لوحة، أو مستند كامل، مع خطوات اختيارية)
`GET`	`/v1/projects`	سرد مشاريعك
`GET`	`/v1/projects/{id}`	مشروع واحد مع مستنده
`PUT`	`/v1/projects/{id}/document`	استبدال المستند كله
`POST`	`/v1/projects/{id}/run`	تطبيق عملية واحدة أو قائمة خطوات
`POST`	`/v1/projects/{id}/undo`	التراجع عن آخر تغيير
`POST`	`/v1/projects/{id}/redo`	إعادة
`GET`	`/v1/projects/{id}/preview?size=1024`	معاينة PNG مجانية، الضلع الطويل حتى `size` بكسل
`POST`	`/v1/projects/{id}/export`	تصدير PNG أو JPEG أو WebP؛ خطوات اختيارية لهذا الملف وحده
`POST`	`/v1/render`	إنتاج دون حالة لمستند كامل
`GET`	`/v1/exports`	سرد تصديراتك
`GET`	`/v1/exports/{id}/file`	تنزيل تصدير
`DELETE`	`/v1/projects/{id}`	حذف مشروع

العمليات

كل عملية كائن يحمل op ومعاملاتها. تُحدَّد الطبقات بـ id أو بالاسم؛ ومن دون layer تُستخدم الطبقة النشطة. تتجاهل الأسماء حالة الأحرف والمسافات، فـ "Linear Dodge (Add)" و"linearDodge" نمط الدمج نفسه. مع steps تُنفَّذ بالترتيب وتتوقف عند أول خطأ (ما لم تضع "stopOnError": false)؛ وتبقى الخطوات التي سبقته مطبَّقة.

الطبقات
النص
الأشكال
التحويل
تعديلات على طبقة
المرشحات
طبقات التعديل
أقنعة الطبقات
تأثيرات الطبقات
اللوحة
المشروع

الطبقات

العملية	المعاملات	ما تفعله
`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.

النص

العملية	المعاملات	ما تفعله
`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.

الأشكال

العملية	المعاملات	ما تفعله
`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.

التحويل

العملية	المعاملات	ما تفعله
`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.

تعديلات على طبقة

العملية	المعاملات	ما تفعله
`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.

المرشحات

العملية	المعاملات	ما تفعله
`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).

طبقات التعديل

العملية	المعاملات	ما تفعله
`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).

أقنعة الطبقات

العملية	المعاملات	ما تفعله
`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.

تأثيرات الطبقات

العملية	المعاملات	ما تفعله
`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.

اللوحة

العملية	المعاملات	ما تفعله
`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.

المشروع

العملية	المعاملات	ما تفعله
`project.state`	—	The whole document.

أنماط الدمج

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

عائلات الخطوط

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

القوالب

مرّر steps إلى استدعاء التصدير فتُطبَّق على نسخة من المشروع لذلك الملف وحده. قالب واحد، وملفات كثيرة: غيّر النص بـ text.set والصورة بـ layer.setImage الذي يحتفظ بصندوق الطبقة.

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

الإنتاج دون حالة

يأخذ POST /v1/render مستندًا كاملًا document (كما يعود في project.document) وخطوات steps اختيارية وخيارات التصدير، ولا يحفظ مشروعًا. مع "response": "image" تكون الاستجابة ملف الصورة.

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

الأخطاء

تعود الأخطاء بصيغة JSON مع code ثابت ورسالة detail بلغة حسابك. الخطوة الفاشلة تُبلغ أي معامل كان خاطئًا. عند استهلاك عمليات الخطة يردّ الـ API بالرمز 402 مع quota_renders.

الحدود

رفع حتى 50 MB و12,000 بكسل للضلع.
لوحة حتى 20,000 بكسل للضلع، ضمن ميغابكسلات خطتك.
حتى 200 خطوة في الاستدعاء.
معاينات حتى 2,048 بكسل على الضلع الطويل.
الميغابكسلات والطبقات والمشاريع والتخزين وعمليات الإنتاج شهريًا تعتمد على الخطة: انظر الأسعار.