Tài liệu tham khảo Jenova Agent API

URL cơ sở: https://api.jenova.ai/v1

Xác thực: Bearer token trong tiêu đề Authorization

Mục lục

• Tổng quan
• Bắt đầu nhanh
• Khái niệm cốt lõi
• Xác thực
• Điểm cuối API
  • API Tin nhắn
  • API Phiên
  • Thao tác
  • Tín dụng
  • API Tác nhân
  • Mô hình
  • Tài liệu
• Truyền phát trực tuyến (SSE)
• Tích hợp Máy chủ MCP
• Thanh toán
• Giới hạn tốc độ
• Xử lý lỗi
• Phân trang
• Bản địa hóa
• Quyền riêng tư và Dữ liệu
• Hỗ trợ

Tổng quan

Xây dựng và triển khai các tác nhân AI sẵn sàng cho môi trường sản xuất mà không cần tự lắp ráp toàn bộ hạ tầng nền tảng. Jenova Agent API tập hợp mọi khả năng cốt lõi vào một dịch vụ được quản lý duy nhất:

Bộ công nghệ Tác nhân đầy đủ

• Điều phối Tác nhân: Một lớp điều phối thống nhất phối hợp các mô hình, công cụ, bộ nhớ và truy xuất trên các luồng công việc phức tạp.
• Bộ nhớ & Ngữ cảnh: Bộ nhớ hội thoại và ngữ cảnh không giới hạn được tích hợp sẵn trong mọi phiên. Không cần quản lý trạng thái bên ngoài.
• Công cụ & MCP: Số lượng tích hợp công cụ không giới hạn với các công cụ gốc của nền tảng và bất kỳ máy chủ MCP từ xa nào, sẵn sàng sử dụng ngay.
• Sử dụng bất kỳ Mô hình nào: Vận hành các tác nhân của bạn bằng các mô hình từ OpenAI, Anthropic, Google, xAI, Qwen và nhiều hơn nữa thông qua một tích hợp duy nhất.
• Lưu trữ được quản lý toàn diện: Cơ sở dữ liệu quan hệ và vector được quản lý với RAG tích hợp sẵn. Không cần cấp phát hoặc mở rộng hạ tầng.
• Chuẩn sản xuất: Được sử dụng bởi hàng trăm nghìn người dùng. Hạ tầng được quản lý toàn diện, API ổn định, được xây dựng cho lưu lượng truy cập sản xuất.

Bắt đầu nhanh

1. Lấy Khóa API của bạn

Tạo một khóa API từ bảng điều khiển dành cho nhà phát triển tại www.jenova.ai/platform. Các khóa sử dụng định dạng jnv_sk_* và được truyền dưới dạng Bearer token.

2. Chọn hoặc Tạo một Tác nhân

Chọn một tác nhân dựng sẵn từ nền tảng, hoặc tạo một tác nhân tùy chỉnh trong bảng điều khiển với các chỉ dẫn, cấu hình mô hình, tệp cơ sở kiến thức, công cụ và máy chủ MCP.

3. Gửi Tin nhắn đầu tiên của bạn

Tạo một phiên và gửi một tin nhắn trong một lần gọi:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

Phản hồi được truyền trở lại dưới dạng Server-Sent Events:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Ghi lại session_id từ stream_started để dùng cho các yêu cầu tiếp theo. Đối với các phản hồi JSON đồng bộ, xem Gửi Tin nhắn.

Khái niệm cốt lõi

Tác nhân

Một tác nhân AI mà bạn tương tác qua API. Mỗi tác nhân có một slug duy nhất (ví dụ: my-support-agent) được dùng làm giá trị agent trong các lệnh gọi API.

• Dựng sẵn: Chọn từ các tác nhân hiện có trên nền tảng.
• Tùy chỉnh: Cấu hình tác nhân riêng của bạn trong bảng điều khiển với các chỉ dẫn, mô hình, cơ sở kiến thức, công cụ và máy chủ MCP.

Phiên

Một luồng hội thoại độc lập giữa một người dùng cuối và một tác nhân.

• Định danh: ID có tiền tố (ví dụ: ses_abc123)
• Phạm vi: Có thể tồn tại nhiều phiên cho cùng một tác nhân và người dùng cuối, mỗi phiên có trạng thái hội thoại độc lập
• Vòng đời: Các phiên tồn tại vô thời hạn cho đến khi bị xóa qua API. Đối với các nhiệm vụ một lần không lưu trữ, hãy sử dụng POST /messages với ephemeral: true
• Cách ly nền tảng: Các phiên API tách biệt hoàn toàn với các hội thoại trong ứng dụng web Jenova. Người dùng cuối, lịch sử phiên và thanh toán là độc lập giữa API và ứng dụng web.

Tin nhắn

Một mục đơn lẻ trong lịch sử hội thoại của một phiên, được trả về bởi các điểm cuối Tin nhắn. Mỗi tin nhắn bao gồm một đối tượng from có cấu trúc với type ("user" hoặc "agent") và name, cùng với type của tin nhắn:

• external - một tin nhắn hội thoại được dự định hiển thị dưới dạng nội dung chat.
• internal - một tin nhắn tùy chọn đại diện cho các bước làm việc của tác nhân trong một lượt chạy, chẳng hạn như lệnh gọi công cụ hoặc truy xuất.

Lượt chạy

Một lần thực thi tác nhân đơn lẻ được tạo ra khi bạn gửi một tin nhắn. Một lượt chạy có một run_id, có thể truyền phát các sự kiện trong khi đang hoạt động, và tạo ra một hoặc nhiều tin nhắn hoàn chỉnh. Mỗi phiên chỉ có thể có một lượt chạy đang hoạt động tại một thời điểm.

Người dùng cuối

Trường user giới hạn phạm vi các phiên cho một người dùng cuối trong ứng dụng của bạn. Hãy sử dụng một ID ổn định và không mang thông tin định danh, chẳng hạn như ID người dùng nội bộ hoặc UUID của bạn. Tránh sử dụng email hoặc các thông tin cá nhân khác trừ khi ứng dụng của bạn yêu cầu. Các phiên được tạo với cùng giá trị user được nhóm lại với nhau, cho phép liệt kê phiên theo từng người dùng.

Nếu user bị bỏ qua, phiên sẽ được giới hạn phạm vi theo tài khoản nhà phát triển của bạn và không thể lọc theo người dùng cuối sau này. Hãy truyền user trong môi trường sản xuất.

Đối với các yêu cầu trên phiên đã tồn tại, user là một cơ chế bảo vệ quyền sở hữu tùy chọn. Nếu bạn cung cấp trường này, nó phải khớp với giá trị user đã dùng khi phiên được tạo; nếu không, API sẽ trả về 404 session_not_owned. Hãy gửi trường này như một tham số truy vấn trong các yêu cầu GET và DELETE, và trong phần nội dung JSON của các yêu cầu POST và PATCH.

Xác thực

Xác thực mọi yêu cầu bằng Bearer token trong tiêu đề Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Khóa API được tạo từ bảng điều khiển dành cho nhà phát triển.

User-Agent là tùy chọn. Các SDK có thể thiết lập giá trị này để phục vụ chẩn đoán, nhưng API không yêu cầu điều đó.

Định dạng khóa: Khóa bắt đầu bằng tiền tố jnv_sk_ theo sau là một chuỗi ngẫu nhiên được mã hóa base62.

Giới hạn: Mỗi tài khoản nhà phát triển có thể có tối đa 10 khóa API đang hoạt động.

Điểm cuối API

API Tin nhắn

Gửi Tin nhắn là đường dẫn API chính. Sử dụng POST /messages cho tin nhắn đầu tiên; nó sẽ tạo phiên và bắt đầu lượt chạy trong một yêu cầu duy nhất. Sử dụng POST /sessions/{session_id}/messages khi tiếp tục một session_id đã được ghi lại.

Gửi Tin nhắn

POST /messages

Tạo một phiên lâu dài và gửi tin nhắn đầu tiên trong một yêu cầu nguyên tử duy nhất. Đặt ephemeral: true để tạo yêu cầu truyền phát trực tuyến một lần không lưu trữ, không lưu phiên hoặc lịch sử tin nhắn, không trả về ID phiên, và không thể tiếp tục.

Nội dung yêu cầu

Ví dụ - Truyền phát trực tuyến (mặc định)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

Phản hồi là một luồng SSE (xem Truyền phát trực tuyến (SSE) để biết định dạng sự kiện). Các yêu cầu lâu dài bao gồm session_id mới; các yêu cầu ephemeral: true không có session_id và phải sử dụng truyền phát trực tuyến.

Ví dụ - JSON (không truyền phát trực tuyến)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Phản hồi

Các phản hồi truyền phát trực tuyến phát ra các sự kiện SSE được mô tả trong Truyền phát trực tuyến (SSE). Các phản hồi không truyền phát trực tuyến trả về cấu trúc JSON của tin nhắn được trình bày trong Tiếp tục Phiên, bao gồm stop_reason và usage cho yêu cầu đã hoàn tất.

Nếu một lượt chạy không truyền phát trực tuyến vẫn đang được xử lý sau 90 giây, API sẽ trả về 202 Accepted với status: "processing", session_id, run_id, và message. Lượt chạy tiếp tục sau khi phản hồi được gửi hoặc khi client ngắt kết nối; hãy kiểm tra các tin nhắn của phiên, hoặc sử dụng truyền phát trực tuyến cho các luồng công việc dài hơn.

Lỗi

Tiếp tục Phiên

POST /sessions/{session_id}/messages

Gửi một tin nhắn đến một phiên liên tục hiện có và nhận phản hồi từ tác nhân. Theo mặc định, phản hồi được truyền phát trực tuyến qua SSE; đặt stream: false để nhận JSON.

Nội dung yêu cầu

Ví dụ - Truyền phát trực tuyến (mặc định)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Ví dụ - JSON (không truyền phát trực tuyến)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Phản hồi 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Nếu phiên đã có một lượt chạy đang hoạt động hoặc tin nhắn đang chờ xử lý, API trả về JSON 202 Accepted với status: "queued", session_id, run_id, và message_id. Tin nhắn của người dùng sẽ được xử lý bởi lượt chạy đang hoạt động.

Lỗi

Tính bất biến (Idempotency)

POST /messages và POST /sessions/{session_id}/messages chấp nhận tiêu đề Idempotency-Key tùy chọn. Hãy sử dụng một khóa duy nhất cho mỗi lần gửi hợp lệ của người dùng để việc thử lại mạng hoặc gửi trùng lặp không tạo ra các lượt chạy trùng lặp.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Không truyền phát trực tuyến: Việc thử lại sẽ trả về phản hồi 200 hoặc 202 đã được lưu, kèm theo tiêu đề Idempotent-Replayed: true.

Truyền phát trực tuyến: Luồng dữ liệu không được phát lại. Việc thử lại trong khi đang chạy hoặc sau khi hoàn tất sẽ trả về một lỗi bất biến cùng với run_id gốc và, đối với các yêu cầu lưu trữ lâu dài, session_id. Sử dụng GET /sessions/{session_id}/runs/{run_id} để kiểm tra một lượt chạy đang hoạt động, hoặc GET /sessions/{session_id}/messages để lấy các kết quả đã được lưu trữ.

Ví dụ về việc thử lại truyền phát trực tuyến đã hoàn tất:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Lỗi bất biến

Danh sách Tin nhắn

GET /sessions/{session_id}/messages

Trả về danh sách phân trang các tin nhắn hội thoại hiển thị. Trang đầu tiên chứa các tin nhắn mới nhất; trong mỗi trang, các tin nhắn được sắp xếp theo thứ tự thời gian (cũ nhất trước). sequence là số thứ tự ổn định trong phạm vi phiên.

Tham số truy vấn

Ví dụ

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Phản hồi 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "files": []
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Đối tượng tin nhắn

Đối tượng tệp

Lỗi

Lấy Tin nhắn

GET /sessions/{session_id}/messages/{message_id}

Truy xuất một tin nhắn hiển thị đơn lẻ theo ID.

Phản hồi 200 OK

Trả về một đối tượng tin nhắn đơn lẻ có cấu trúc giống với phản hồi danh sách.

Lỗi

Tệp đính kèm

Truyền các URL HTTPS có thể truy cập công khai trong trường file_urls.

Định dạng được hỗ trợ

• Hình ảnh: JPG, JPEG, PNG, WebP
• Tài liệu: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Mã nguồn: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

Khi liệt kê tin nhắn, các tệp đính kèm sẽ xuất hiện trong mảng files của tin nhắn.

API Phiên

Phiên là các cuộc hội thoại lâu dài giữa một người dùng cuối và một tác nhân. Hầu hết các tích hợp có thể tạo phiên một cách ngầm định bằng POST /messages.

Tạo Phiên

POST /sessions

Tạo một phiên bền vững trống được liên kết với một tác nhân cụ thể. Sử dụng thao tác này khi bạn cần một ID phiên trước tin nhắn đầu tiên; nếu không, hãy ưu tiên sử dụng POST /messages.

Lưu ý: ephemeral không được chấp nhận trên POST /sessions; hãy sử dụng POST /messages với ephemeral: true cho các yêu cầu một lần không lưu trữ.

Nội dung yêu cầu

Ví dụ

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Phản hồi 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Lỗi

Danh sách Phiên

GET /sessions

Trả về danh sách các phiên của bạn theo dạng phân trang, được sắp xếp theo thời điểm cập nhật gần nhất.

Tham số truy vấn

Ví dụ

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Phản hồi 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAxIn0",
  "has_more": true
}

Lỗi

Lấy Phiên

GET /sessions/{session_id}

Truy xuất một phiên đơn lẻ theo ID.

Phản hồi 200 OK

Trả về một đối tượng phiên có cấu trúc giống với phản hồi tạo phiên.

Lỗi

Đổi tên Phiên

PATCH /sessions/{session_id}

Cập nhật tên hiển thị của một phiên.

Nội dung yêu cầu

Phản hồi 200 OK

Trả về đối tượng phiên đã được cập nhật.

Lỗi

Xóa Phiên

DELETE /sessions/{session_id}

Xóa vĩnh viễn một phiên và toàn bộ tin nhắn của phiên đó. Phiên này không được có lượt chạy đang hoạt động.

Phản hồi 204 No Content

Lỗi

Thao tác

Các điểm cuối này là các công cụ khôi phục và chỉnh sửa cho các phiên bền vững (persistent sessions). Hầu hết các tích hợp chỉ cần dùng Hủy; hãy sử dụng các thao tác khác khi bạn cố ý muốn thay đổi hoặc khôi phục trạng thái phiên. Tất cả các thao tác đều hỗ trợ cơ chế bảo vệ quyền sở hữu tùy chọn user được mô tả trong Người dùng cuối.

Hủy Lượt chạy đang hoạt động

POST /sessions/{session_id}/cancel

Hủy lượt chạy tác nhân đang thực hiện hiện tại. Thao tác này không xóa các tin nhắn đã hoàn tất trước khi hủy.

Nội dung yêu cầu

Phản hồi 204 No Content

Lỗi

Hoàn tác Lượt chạy đang hoạt động

POST /sessions/{session_id}/undo

Hủy lượt chạy đang hoạt động, đợi cho lượt chạy đó dừng lại, sau đó xóa mọi tin nhắn mà nó đã thêm vào. Không có đầu ra bổ sung nào được lưu lại sau khi lệnh hoàn tác được thực hiện.

Nội dung yêu cầu

Phản hồi 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Nếu lượt chạy bị hủy trước khi bất kỳ tin nhắn nào được hoàn tất, deleted sẽ là một mảng trống.

Lỗi

Xóa Tin nhắn gần đây

POST /sessions/{session_id}/messages/delete

Xóa N tin nhắn gần đây nhất từ một phiên đang ở trạng thái nghỉ. Phiên không được có lượt chạy đang hoạt động.

Nội dung yêu cầu

Phản hồi 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Lỗi

Phân nhánh Phiên

POST /sessions/{session_id}/fork

Tạo một phiên mới bằng cách sao chép phiên nguồn cho đến một tin nhắn cụ thể. Phiên nguồn không được có lượt chạy đang hoạt động.

Nội dung yêu cầu

Phản hồi 201 Created

Trả về đối tượng phiên vừa được tạo với cấu trúc giống như khi tạo phiên.

Lỗi

Lấy Trạng thái Lượt chạy

GET /sessions/{session_id}/runs/{run_id}

Trả về trạng thái hiện tại của một lượt chạy đang hoạt động. Sử dụng lệnh này sau khi kết nối SSE bị gián đoạn hoặc sau khi nhận được phản hồi idempotency có chứa run_id. Sau khi lượt chạy hoàn tất, hãy lấy kết quả bằng GET /sessions/{session_id}/messages.

Phản hồi 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

Phản hồi cũng có thể bao gồm các gợi ý tiến trình gần đây trong khi lượt chạy vẫn đang hoạt động.

Lỗi

Tín dụng

Lấy Số dư

GET /credits/balance

Trả về số dư tín dụng hiện tại của bạn.

Phản hồi 200 OK

{
  "balance": "123.45"
}

API Tác nhân

Tạo và chỉnh sửa các tác nhân tùy chỉnh trong bảng điều khiển. Hỗ trợ API cho việc tạo và chỉnh sửa tác nhân sẽ sớm ra mắt.

Các luồng công việc theo lịch/nền hiện chưa được hỗ trợ qua API. Hỗ trợ sẽ sớm ra mắt.

Danh sách Tác nhân

GET /agents

Trả về các tác nhân khả dụng cho khóa API của bạn. Sử dụng giá trị agent khi tạo phiên hoặc gửi tin nhắn.

Phản hồi 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Mô hình

Danh sách Mô hình

GET /models

Trả về tất cả các mô hình khả dụng để sử dụng trong trường model khi gửi tin nhắn.

Phản hồi 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "kimi-k2.6",
      "name": "Kimi K2.6",
      "thinking_variant": "kimi-k2.6-thinking"
    }
  ]
}

Các mô hình có thinking_variant hỗ trợ suy luận mở rộng. Sử dụng trực tiếp ID biến thể trong trường model để bật tính năng này.

Nếu không có model nào được chỉ định khi gửi tin nhắn, mô hình mặc định của tác nhân sẽ được sử dụng.

Tài liệu

GET /docs?lang=en
GET /doc?lang=en

Trả về tài liệu tham khảo này dưới dạng Markdown. Sử dụng lang để chọn ngôn ngữ.

Truyền phát trực tuyến (SSE)

Khi stream bị bỏ qua hoặc là true (giá trị mặc định), các phản hồi tin nhắn được gửi dưới dạng Server-Sent Events. Sử dụng các sự kiện message_completed để xác định các tin nhắn đã sẵn sàng để lấy hoặc hiển thị.

Thời gian chờ: Các kết nối SSE duy trì mở tối đa 60 phút. Các yêu cầu không truyền phát trực tuyến chờ tối đa 90 giây, sau đó trả về 202 Accepted trong khi lượt chạy vẫn tiếp tục.

Tiêu đề kết nối

Phản hồi SSE đặt các tiêu đề sau:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id có sẵn trước khi sự kiện SSE đầu tiên xuất hiện.

Kết nối lại và khôi phục

Các luồng SSE không được phát lại. Nếu kết nối bị ngắt, hãy sử dụng session_id và run_id đã ghi lại để khôi phục trạng thái:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Nếu lượt chạy vẫn đang hoạt động, lệnh này trả về trạng thái hiện tại, văn bản một phần và tiến trình gần đây. Nếu trả về 404 not_found, nghĩa là lượt chạy không còn hoạt động; hãy lấy các tin nhắn của phiên để đối chiếu đầu ra đã hoàn tất:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Định dạng khung

Mỗi khung SSE tuân theo định dạng chuẩn sau:

event: <event_type>
data: <json_payload>

Hai dấu xuống dòng kết thúc mỗi khung.

Các loại Sự kiện

Luồng bao gồm các sự kiện vòng đời, delta văn bản, suy nghĩ, tiến trình, cảnh báo, hoàn tất tin nhắn, kết nối MCP, lỗi, cuối cùng và ping. Một số loại sự kiện chỉ được gửi khi có liên quan.

Đối với các yêu cầu tạm thời (ephemeral: true), mọi Sự kiện SSE đều bỏ qua session_id. Chỉ sử dụng run_id để liên kết các Sự kiện trong luồng đó.

Để đối chiếu cuối cùng đối với các yêu cầu bền vững, hãy chờ stream_ended, sau đó gọi List Messages.

Các trường phổ biến trên các Sự kiện phạm vi lượt chạy:

stream_started

Được gửi một lần khi Lượt chạy bắt đầu.

stream_delta

Được gửi liên tục khi Tác nhân tạo ra văn bản phản hồi hiển thị. Nối các giá trị chunk_content theo thứ tự seq để tạo thành phản hồi được truyền phát trực tuyến.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Được gửi liên tục khi Tác nhân phát ra đầu ra suy nghĩ. Sử dụng trường này cho một chỉ báo suy nghĩ riêng biệt hoặc chế độ xem theo dõi; không nối trường này vào văn bản phản hồi cuối cùng.

stream_progress

Báo cáo hoạt động hiển thị cho người dùng trong quá trình tạo, chẳng hạn như đọc tài liệu, tìm kiếm trên web hoặc chờ hành động của người dùng. Những sự kiện này dùng để hiển thị tạm thời trong UI; hãy bỏ qua các trường không xác định. Sử dụng các tin nhắn đã hoàn tất làm lịch sử tin nhắn có thẩm quyền.

Nâng cao: các yêu cầu Tin nhắn chấp nhận include_progress: false để chỉ bỏ qua stream_progress. Các Sự kiện vòng đời, ping, message_completed, lỗi, và các Sự kiện kết thúc vẫn được gửi khi phù hợp.

Một số Sự kiện tiến trình có thể bao gồm url, file_name, hoặc server_name như các gợi ý hiển thị tùy chọn.

message_completed

Được gửi mỗi khi một Tin nhắn hoàn tất và sẵn sàng để lấy hoặc hiển thị.

Đây là một điểm mốc ranh giới, không phải toàn bộ đối tượng Tin nhắn. Hãy lấy Tin nhắn nếu bạn cần nội dung hoặc metadata.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"Jenova"},"type":"external"}

mcp_connection

Được gửi khi tác nhân cần người dùng cuối kết nối hoặc cấp quyền cho một hoặc nhiều máy chủ MCP trước khi có thể tiếp tục. Sự kiện này chỉ khả dụng ở chế độ streaming.

mcp_connection_resolved

Được gửi khi hành động kết nối MCP của người dùng đã được giải quyết hoặc đã hết hạn.

Không có trường bổ sung nào ngoài các trường phổ biến phạm vi lượt chạy.

warning

Được gửi cho các cảnh báo không nghiêm trọng trong một Lượt chạy.

stream_error

Được gửi khi một Lượt chạy thất bại. Một Sự kiện stream_ended cuối cùng có thể theo sau với success:false và stop_reason:"error".

stream_ended

Được gửi một lần khi lượt chạy kết thúc. Đây là sự kiện cuối cùng của luồng.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Ví dụ thất bại:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Các khung giữ kết nối được gửi mỗi 15 giây để tránh việc proxy/CDN hết thời gian chờ. Hãy bỏ qua các sự kiện này trong client của bạn.

Tích hợp Máy chủ MCP

Kết nối các Tác nhân của bạn với các công cụ bên ngoài qua Model Context Protocol (MCP):

• Máy chủ MCP do Jenova quản lý: các máy chủ do Jenova lưu trữ cho tìm kiếm, truy xuất nội dung, tạo tài liệu và các khả năng tích hợp sẵn khác
• Máy chủ MCP từ xa: các máy chủ MCP từ xa khác được cấu hình cho Tác nhân của bạn

Các máy chủ MCP phải được cấu hình trong bảng điều khiển khi tạo hoặc chỉnh sửa Tác nhân của bạn. Để sử dụng máy chủ MCP riêng của bạn, hãy thêm nó vào một Tác nhân tùy chỉnh, sau đó gọi Tác nhân đó qua API. API sẽ thực thi các Công cụ được bật trong cấu hình của Tác nhân; không cần thiết lập thêm trong các yêu cầu API.

Khi một Tác nhân sử dụng các Công cụ MCP trong khi phản hồi, các Sự kiện tiến trình sẽ được gửi trong luồng ngay khi chúng xảy ra:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Nếu tác nhân cần người dùng cuối kết nối hoặc cấp quyền cho một máy chủ MCP trong quá trình chạy, các phản hồi streaming có thể bao gồm các sự kiện mcp_connection và mcp_connection_resolved. Hãy hiển thị danh sách máy chủ kết nối cho người dùng cuối của bạn và mở auth_url được cung cấp khi có. Giữ luồng SSE mở trong khi người dùng kết nối hoặc cấp quyền cho máy chủ.

Sau khi cấp quyền, Jenova lưu trữ token, cửa sổ cấp quyền hiển thị trang hoàn tất, và cùng Lượt chạy đó tiếp tục tự động. Người dùng cuối không cần gửi lại Tin nhắn.

Nếu người dùng cuối không kết nối, cấp quyền, bỏ qua hoặc tắt lời nhắc trước user_action_deadline_unix, lượt chạy kết thúc với stop_reason:"user_action_timeout". Bạn cũng có thể hủy lượt chạy đang hoạt động bằng POST /sessions/{session_id}/cancel.

Lưu trữ auth_url ở phía client. Nếu client bị mất kết nối trong quá trình cấp quyền, URL vẫn còn hiệu lực cho đến user_action_deadline_unix. Đối với các yêu cầu bền vững, hãy kết nối lại bằng Get Run Status, hoặc lấy các tin nhắn sau khi lượt chạy kết thúc.

Các yêu cầu không streaming (stream: false) không hỗ trợ hành động người dùng kết nối MCP; hãy dùng streaming cho các tác nhân có thể cần tương tác này.

Bỏ qua kết nối MCP

POST /sessions/{session_id}/mcp/connection/skip

Hủy một hành động người dùng kết nối MCP đang chờ xử lý và cho phép lượt chạy tiếp tục mà không có kết nối đó.

Để tắt các lời nhắc kết nối trong tương lai cho một máy chủ đối với cùng một người dùng API, hãy bao gồm mcp_server_id và mute. Các giá trị được hỗ trợ là 24h và forever.

Nội dung yêu cầu

Phản hồi 204 No Content

Luồng phát ra sự kiện mcp_connection_resolved, sau đó lượt chạy tiếp tục với cùng run_id.

Lỗi

Thanh toán

Mọi chi phí đều được trừ từ số dư Tín dụng dành cho nhà phát triển của bạn. Xem mức sử dụng và nạp thêm Tín dụng tại www.jenova.ai/platform.

Giá cả

Chi phí Tin nhắn phụ thuộc vào:

• Mô hình - các Mô hình khác nhau có chi phí trên mỗi token khác nhau
• Độ dài ngữ cảnh - Phiên dài hơn tiêu thụ nhiều token đầu vào hơn cho mỗi yêu cầu
• Độ phức tạp của quy trình làm việc - quy trình làm việc dài hơn và việc sử dụng Công cụ nhiều hơn (tìm kiếm web, tạo tệp, phân tích tài liệu) làm tăng tổng mức tiêu thụ token

Chi phí thực tế được trả về dưới dạng stream_ended.usage.cost đối với các yêu cầu Truyền phát trực tuyến và usage.cost đối với các yêu cầu JSON không truyền phát trực tuyến.

Tạm giữ tín dụng

Mỗi Lượt chạy Tin nhắn mới sẽ đặt một khoản tạm giữ $0.50 trên số dư Tín dụng của bạn trước khi việc thực thi bắt đầu. Điều này nhằm dự trữ tiền cho Lượt chạy. Các Tin nhắn tiếp theo đang trong hàng đợi của một Lượt chạy đang hoạt động không tạo ra khoản tạm giữ bổ sung; mức sử dụng của Lượt chạy đang hoạt động được kiểm tra dựa trên số dư còn lại của bạn.

Khi Lượt chạy hoàn tất, khoản tạm giữ được quyết toán theo chi phí thực tế và phần chênh lệch được giải phóng. Các Lượt chạy bị hủy và thất bại chỉ bị tính phí cho mức sử dụng đã phát sinh. Nếu một yêu cầu thất bại trước khi đến được Mô hình, toàn bộ khoản tạm giữ sẽ được giải phóng.

Điều này có nghĩa là số dư khả dụng của bạn có thể tạm thời hiển thị thấp hơn trong khi các yêu cầu đang xử lý. Bạn cần có ít nhất $0.50 trong số dư khả dụng để gửi một Tin nhắn đến một Phiên hiện có hoặc để gửi một Tin nhắn tạm thời. Yêu cầu POST /messages bền vững đầu tiên sẽ tạo ra một Phiên và cần ít nhất $0.51 để trang trải khoản tạm giữ Tin nhắn cùng với phí tạo Phiên.

Giới hạn tốc độ

Mọi tài khoản nhà phát triển đều chịu ba chiều Giới hạn tốc độ:

Các yêu cầu GET và HEAD không tiêu thụ slot đồng thời. cancel, undo và mcp/connection/skip cũng không tiêu thụ slot đồng thời, vì vậy các thao tác này vẫn khả dụng khi tất cả slot đang được sử dụng. Các yêu cầu này vẫn được tính vào RPM và RPD.

Tiêu đề phản hồi

Các phản hồi API đã xác thực bao gồm các tiêu đề giới hạn tốc độ:

Khi vượt quá giới hạn, API trả về 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 12 seconds."
  }
}

Xử lý lỗi

Các lỗi HTTP tức thời và lỗi lượt chạy không truyền phát trực tuyến tuân theo một cấu trúc thống nhất:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

Thông báo lỗi được bản địa hóa dựa trên tham số lang (xem Bản địa hóa).

Các lỗi Lượt chạy truyền phát trực tuyến được gửi dưới dạng các sự kiện stream_error. Một lượt chạy thất bại vẫn có thể gửi một sự kiện stream_ended cuối cùng với success:false và stop_reason được thiết lập. Các lỗi Lượt chạy không truyền phát trực tuyến cũng có thể bao gồm một đối tượng usage ở cấp cao nhất khi có dữ liệu chi phí.

Các lỗi riêng của từng điểm cuối được ghi chú trực tiếp trong phần mô tả của mỗi điểm cuối.

Lỗi Lượt chạy sau khi Bắt đầu

Lỗi Lượt chạy xuất hiện sau khi một lượt chạy tin nhắn đã bắt đầu. Ở chế độ truyền phát trực tuyến, chúng xuất hiện dưới dạng các sự kiện stream_error và có thể được theo sau bởi stream_ended với success:false. Ở chế độ không truyền phát trực tuyến, chúng được trả về dưới dạng phản hồi lỗi JSON kèm mã trạng thái HTTP dưới đây.

Phân trang

Các điểm cuối danh sách sử dụng phân trang dựa trên con trỏ (cursor-based pagination):

{
  "items": [],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAyIn0",
  "has_more": true
}

Truyền next_cursor làm tham số truy vấn cursor để lấy trang tiếp theo. Khi has_more là false, không còn kết quả nào nữa.

Bản địa hóa

Tất cả các điểm cuối đều nhận tham số truy vấn tùy chọn lang để kiểm soát ngôn ngữ của thông báo lỗi và bất kỳ nội dung được bản địa hóa nào.

Bạn có thể thêm ?lang=xx vào bất kỳ URL yêu cầu nào:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Ngôn ngữ được hỗ trợ: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Quyền riêng tư và Dữ liệu

Jenova không sử dụng các prompt API, đầu ra, lịch sử hội thoại, tệp đã tải lên, hướng dẫn tác nhân hoặc cơ sở kiến thức để huấn luyện các mô hình của Jenova.

Đối với các nhà cung cấp mô hình bên thứ ba, Jenova sử dụng các kênh API thương mại, cài đặt tài khoản, các cam kết hợp đồng hoặc các tùy chọn từ chối (opt-out) nhằm ngăn nội dung của khách hàng bị sử dụng để huấn luyện các mô hình của nhà cung cấp.

Jenova lưu trữ và xử lý dữ liệu API bằng cơ sở hạ tầng tại Hoa Kỳ. Các nhà cung cấp bên thứ ba có thể xử lý dữ liệu tại các khu vực pháp lý khác như được mô tả trong Chính sách Quyền riêng tư và Điều khoản Sử dụng.

Để biết đầy đủ chi tiết, hãy xem Điều khoản Sử dụng, Chính sách Quyền riêng tư, và Chính sách Sử dụng.

Hỗ trợ

• Bảng điều khiển: www.jenova.ai/platform
• Email: [email protected]