n8n-nodes-codesave-gateway

Community node để gọi Code-Save AI Gateway từ n8n — chat đồng bộ, job bất đồng bộ (ảnh/video/việc nặng), liệt kê model, và nhận webhook callback.

Gateway là một cổng AI thống nhất (Gemini/Vertex…) với hàng đợi job, retry + fallback model, tính phí và log tập trung. Node này là client chính thức cho n8n.

Cài đặt

Gói phát hành công khai trên npmjs → cài thẳng từ UI, không cần cấu hình registry, không cần vào máy chủ.

Trong n8n (khuyên dùng): Settings → Community Nodes → Install → nhập n8n-nodes-codesave-gateway → Install.

Thủ công (self-host):

cd ~/.n8n/nodes
npm install n8n-nodes-codesave-gateway
# khởi động lại n8n

Node là client mỏng — không chứa secret. Quyền truy cập gateway do API key bạn nhập trong credential quyết định; cài node mà không có key hợp lệ thì không gọi được gì.

Hướng dẫn đầy đủ: https://gateway.code-save.com/docs/cai-dat/

Credential

Tạo credential Code-Save Gateway API:

| Trường | Bắt buộc | Mô tả | |---|---|---| | Base URL | ✓ | Mặc định https://gateway.code-save.com | | API Key | ✓ | csg_<project>_<secret> — lấy trong dashboard | | Webhook Signing Secret | — | Chỉ cần cho node Trigger (verify chữ ký) |

Nút Test gọi GET /v1/models để kiểm tra key.

Node: Code-Save Gateway

Resource: Chat (Sync)

Complete → POST /v1/chat. Gửi hội thoại, nhận trả lời ngay trong luồng. Hỗ trợ temperature/top_p/max_tokens, stop sequences, JSON mode, và thinking (budget + include thoughts). Bật Simplify để lấy gọn content / reasoning_content / usage.

Đa phương thức (ảnh/audio): mỗi message có field Attachments (Binary Fields) — nhập tên binary field của item (cách nhau dấu phẩy). Node tự đọc mimeType, base64-hoá và gắn kèm dưới dạng image/* hoặc audio/*. Bỏ trống = chỉ gửi text (tương thích ngược). Model phải hỗ trợ loại input tương ứng (đa số Gemini nhận ảnh; 2.5+ nhận audio).

Dùng cho: chat ngắn, tương tác (p50 ~3s). Đường sync có deadline gateway (SYNC_MAX_MS) và giữ 1 slot suốt thời gian chạy — không hợp cho việc dài.

Resource: Job (Async)

| Operation | Ý nghĩa | |---|---| | Submit | Đẩy job vào hàng đợi, trả job_id ngay. Kết quả nhận qua Trigger (webhook) hoặc poll. Điền Callback URL = URL của node Trigger. | | Submit and Wait | Submit rồi tự poll tới khi xong. Tuyến tính như sync nhưng có độ bền của async, không cần dựng webhook, và không bị HTTP timeout chặn. | | Get | GET /v1/jobs/:id — trạng thái + result_url (khi completed). | | Download Result | Job completed → tải file (ảnh/video) từ result_url về binary. | | Cancel | DELETE /v1/jobs/:id — chỉ khi pending/running. |

Hỗ trợ priority, idempotency_key, max_attempts (retry cùng model), fallback models (nhảy model giữ vị trí FIFO), và action generateContent / predict / predictLongRunning (Veo) / streamGenerateContent.

Kết quả trả về (đọc kỹ — breaking change 2026-07-23)

Kết quả ảnh/video của job KHÔNG còn base64 inline trong response_payload — phải tải qua result_url. Đây là cờ slim_images (bật 2026-07-23) để gateway thôi lưu ảnh 2 lần.

| Loại job | response_payload chứa gì | Lấy kết quả ở đâu | |---|---|---| | Ảnh đơn (gemini-*-image, sampleCount=1) | chỉ {done, result_saved, result_ext} — đã gỡ base64 | result_url (hoặc operation Download Result) | | Nhiều ảnh (sampleCount>1, nhiều inlineData) | giữ base64 (lưới an toàn — result_url chỉ mang ảnh đầu) | base64 inline hoặc result_url (ảnh đầu) | | Video (veo-*) | {done, result_saved, result_ext, operation_name} — không có bytes | result_url (hoặc Download Result) | | Audio / TTS (gemini-*-tts) | {done, result_saved, result_ext:"wav"} — đã gỡ base64; PCM thô đã được bọc → WAV | result_url (hoặc Download Result) | | Chat/text (POST /v1/chat) | không đổi | content trong response |

Cách dùng chuẩn: khi nhận completed (qua Trigger hoặc Submit-and-Wait) → chạy Download Result với Job ID để lấy file binary, hoặc tự GET result_url.

• result_url không cần Authorization (token nằm trong URL). Token hết hạn ~24h, nhưng mỗi lần Get lại cấp token mới → đối soát muộn vẫn tải được miễn file còn.
• File kết quả giữ tối đa 7 ngày (2 ngày nếu đã ack-consumed) → tải & lưu về kho của bạn ngay khi completed.
• Lưới đỡ tạm: gọi GET /v1/jobs/:id?include_base64=1 để dựng lại base64 ảnh đầu từ file đĩa (tạm thời — nên chuyển sang result_url).

Chọn sync hay async là theo độ nặng của việc, không phải mệnh lệnh:

• Việc nhẹ → Chat (Sync).
• Việc nặng, muốn tuyến tính, ngại webhook → Job → Submit and Wait (mặc định khuyên dùng).
• Fire-and-forget, nhiều việc song song → Job → Submit + Trigger.
• Veo/video → Submit với action predictLongRunning (async về bản chất).

Resource: Model

List → GET /v1/models. Danh sách model đang phục vụ (dùng cho dropdown, tự động). Admin bật model mới ở gateway là dropdown thấy ngay ở lần load kế tiếp — không cần cập nhật/publish lại node. Node chỉ truyền payload nên tham số model mới cũng dùng được ngay (ràng buộc tham số xem /v1/models/catalog · /docs).

TTS Gemini native: chọn model gemini-2.5-flash-tts / gemini-2.5-pro-tts (tên cũ -preview-tts vẫn chạy nhờ alias), resource Job action generateContent, Payload (JSON):

{
  "contents": [{ "role": "user", "parts": [{ "text": "Xin chào, đây là giọng đọc thử." }] }],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": { "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }
  }
}

Kết quả là job audio (result_ext=wav) — nối Download Result để lấy file như ảnh/video. ~30 giọng dựng sẵn, đa giọng qua multiSpeakerVoiceConfig.

Node: Code-Save Gateway Trigger

Webhook nhận callback job. Dán URL Production của node vào Callback URL khi Submit.

• Verify HMAC: header X-Gateway-Signature: sha256=<hex> = HMAC-SHA256(raw body, Webhook Signing Secret). So sánh timing-safe.
• Chống replay: bỏ delivery có ts cũ hơn 300s.
• Chống lặp: dedup theo job_id:event:ts + terminal-guard job_id:final (job đã xong thì bỏ mọi delivery sau).
• Lọc theo event completed / failed / retrying.

Retry & lỗi

Mọi request tự thử lại khi gặp 429 theo header Retry-After (tối đa 2 lần) — bao gồm project_concurrency_limit, no_slot_available, gateway_overloaded, budget. 4xx khác ném lỗi ngay.

410 model_retired_candidate_unconfirmed: model đã qua hạn ngừng phục vụ mà gateway chưa xác minh model thay thế → đổi model trong node sang model mới (xem gợi ý successor trong detail). Nếu đã có thay thế xác minh, gateway tự chuyển trong suốt (không lỗi).

License

MIT