API KeysTasks

Tasks

Theo dõi trạng thái và lấy kết quả của các tác vụ bất đồng bộ bằng API Key.


Tasks

Nhiều API của Notex xử lý theo cơ chế bất đồng bộ.

Thay vì chờ kết quả hoàn tất trong request đầu tiên, API sẽ trả về một task_id. Bạn dùng Tasks API để kiểm tra tiến độ và lấy kết quả cuối cùng.

Các tính năng thường trả về task_id gồm:

  • Tạo note
  • Flashcards
  • Quiz
  • Mindmap
  • Slide
  • Podcast
  • Shorts
  • Translate

Luồng xử lý cơ bản:

Gửi request tạo nội dung

Nhận task_id

Kiểm tra trạng thái task

SUCCESS: sử dụng kết quả
FAILURE: xử lý lỗi

Base URL:

https://api.notexapp.com

Gửi API Key trong header X-API-Key:

-H "X-API-Key: ntx_live_..."

Poll task result

GET /v1/create/tasks/{task_id}/result

Trả về trạng thái hiện tại và kết quả của một tác vụ bất đồng bộ.

Path parameter

ParameterTypeRequiredDescription
task_idstringYesID được trả về từ API khởi tạo tác vụ

Example request

curl https://api.notexapp.com/v1/create/tasks/task_123456/result \
  -H "X-API-Key: ntx_live_..."

Thay task_123456 bằng task_id nhận được từ request trước.


Task statuses

StatusMeaningAction
PENDINGTác vụ đang chờ được xử lýTiếp tục polling
PROCESSINGTác vụ đang được xử lýTiếp tục polling
SUCCESSTác vụ đã hoàn tấtĐọc kết quả trong data và dừng polling
FAILURETác vụ thất bạiĐọc thông tin lỗi và dừng polling
FAILTác vụ thất bạiXử lý tương tự FAILURE

Tích hợp nên hỗ trợ cả FAILUREFAIL.


Pending or processing

Khi tác vụ chưa hoàn tất, API trả về PENDING hoặc PROCESSING.

{
  "status": "PROCESSING",
  "step": "transcribing",
  "progress": 35,
  "estimated_time": 60
}

Processing fields

FieldTypeDescription
status"PENDING" | "PROCESSING"Trạng thái hiện tại của tác vụ
stepstringBước xử lý hiện tại, nếu có
progressnumberTiến độ ước tính từ 0 đến 100
estimated_timenumberThời gian ước tính còn lại, tính bằng giây

Các field tiến độ là tùy chọn và có thể không xuất hiện trong mọi tác vụ.

Ví dụ response tối thiểu:

{
  "status": "PROCESSING"
}

Successful result

Khi tác vụ hoàn tất, API trả về trạng thái SUCCESS và kết quả trong data.

{
  "status": "SUCCESS",
  "data": {
    "note_id": "665f...",
    "title": "Introduction to Machine Learning",
    "summary": "An overview of machine learning concepts..."
  }
}

Common result fields

FieldTypeDescription
data.note_idstringID của note được tạo hoặc cập nhật
data.titlestringTiêu đề của nội dung
data.summarystringNội dung tóm tắt, nếu có
data.typestringLoại kết quả được tạo
data.audio_urlstringURL file âm thanh, nếu tác vụ tạo audio
data.youtube_urlstringURL YouTube nguồn, nếu có
data.viewsstringThông tin lượt xem, nếu có
messagestringThông báo bổ sung từ API

Cấu trúc data phụ thuộc vào loại tác vụ.

Ví dụ:

Tác vụKết quả có thể trả về
Create notenote_id, title, summary
FlashcardsThông tin bộ flashcards
QuizThông tin bộ câu hỏi
MindmapDữ liệu hoặc URL mindmap
SlideThông tin bộ slide
Podcastaudio_url và metadata
TranslateNội dung hoặc ID note đã dịch

Không nên giả định mọi task đều trả về cùng một cấu trúc data.


Failed result

Khi tác vụ thất bại, API trả về FAILURE hoặc FAIL.

{
  "status": "FAILURE",
  "error": "Unsupported file format",
  "error_key": "unsupported_file_format",
  "message": "The uploaded file format is not supported."
}

Error fields

FieldTypeDescription
status"FAILURE" | "FAIL"Trạng thái thất bại
errorstringNội dung lỗi ngắn
error_keystringMã lỗi ổn định để xử lý trong code
messagestringMô tả chi tiết hơn về lỗi

Khi có error_key, nên ưu tiên sử dụng field này để xác định loại lỗi thay vì so sánh trực tiếp nội dung error hoặc message.


Polling guidance

Nên kiểm tra trạng thái task theo chu kỳ thay vì gọi liên tục.

SettingRecommendation
Polling intervalMỗi 3–5 giây
Stop conditionSUCCESS, FAILURE hoặc FAIL
TimeoutTự thiết lập theo loại tác vụ
CancellationHỗ trợ AbortSignal khi có thể

Không nên:

  • Poll API nhiều lần mỗi giây.
  • Tiếp tục polling sau khi task đã hoàn tất.
  • Coi timeout phía client là task đã thất bại.
  • Tạo lại task ngay khi request polling tạm thời gặp lỗi mạng.

Timeout của ứng dụng chỉ có nghĩa là ứng dụng đã ngừng chờ. Task trên Notex có thể vẫn đang tiếp tục xử lý.


Basic polling example

Ví dụ Bash sau kiểm tra task mỗi 5 giây:

TASK_ID="task_123456"

while true; do
  RESPONSE=$(curl -s \
    "https://api.notexapp.com/v1/create/tasks/$TASK_ID/result" \
    -H "X-API-Key: ntx_live_...")

  STATUS=$(echo "$RESPONSE" | jq -r '.status')

  if [ "$STATUS" = "SUCCESS" ]; then
    echo "$RESPONSE"
    break
  fi

  if [ "$STATUS" = "FAILURE" ] || [ "$STATUS" = "FAIL" ]; then
    echo "$RESPONSE" >&2
    exit 1
  fi

  sleep 5
done

JavaScript polling example

type TaskStatus =
  | 'PENDING'
  | 'PROCESSING'
  | 'SUCCESS'
  | 'FAILURE'
  | 'FAIL';

interface TaskProcessingResponse {
  status: 'PENDING' | 'PROCESSING';
  step?: string;
  progress?: number;
  estimated_time?: number;
}

interface TaskSuccessResponse<T> {
  status: 'SUCCESS';
  data: T;
  message?: string;
}

interface TaskFailureResponse {
  status: 'FAILURE' | 'FAIL';
  error?: string;
  error_key?: string;
  message?: string;
}

type TaskResultResponse<T> =
  | TaskProcessingResponse
  | TaskSuccessResponse<T>
  | TaskFailureResponse;

interface PollTaskOptions {
  intervalMs?: number;
  timeoutMs?: number;
  signal?: AbortSignal;
  onProgress?: (task: TaskProcessingResponse) => void;
}

async function pollTask<T>(
  taskId: string,
  apiKey: string,
  options: PollTaskOptions = {},
): Promise<T> {
  const {
    intervalMs = 4000,
    timeoutMs = 120000,
    signal,
    onProgress,
  } = options;

  const startedAt = Date.now();

  while (Date.now() - startedAt < timeoutMs) {
    if (signal?.aborted) {
      throw new DOMException('Task polling was cancelled', 'AbortError');
    }

    const response = await fetch(
      `https://api.notexapp.com/v1/create/tasks/${encodeURIComponent(taskId)}/result`,
      {
        headers: {
          'X-API-Key': apiKey,
        },
        signal,
      },
    );

    if (!response.ok) {
      throw new Error(`Failed to poll task: HTTP ${response.status}`);
    }

    const result = (await response.json()) as TaskResultResponse<T>;

    if (result.status === 'SUCCESS') {
      return result.data;
    }

    if (result.status === 'FAILURE' || result.status === 'FAIL') {
      throw new Error(
        result.message ??
          result.error ??
          result.error_key ??
          'Task failed',
      );
    }

    onProgress?.(result);

    await new Promise<void>((resolve, reject) => {
      const timer = setTimeout(resolve, intervalMs);

      signal?.addEventListener(
        'abort',
        () => {
          clearTimeout(timer);
          reject(new DOMException('Task polling was cancelled', 'AbortError'));
        },
        { once: true },
      );
    });
  }

  throw new Error('Task polling timed out');
}

Usage

interface CreateNoteResult {
  note_id: string;
  title?: string;
  summary?: string;
}

const result = await pollTask<CreateNoteResult>(
  'task_123456',
  process.env.NOTEX_API_KEY!,
  {
    intervalMs: 4000,
    timeoutMs: 180000,
    onProgress(task) {
      console.log(task.step, task.progress);
    },
  },
);

console.log(result.note_id);

TypeScript types

View TypeScript types


Typical integration flow

const createResponse = await createContent();

const taskId = createResponse.data.task_id;

const result = await pollTask(taskId, apiKey);

Thứ tự xử lý nên là:

  1. Gọi API tạo nội dung.
  2. Lưu task_id.
  3. Poll Tasks API mỗi 3–5 giây.
  4. Hiển thị tiến độ nếu response có step hoặc progress.
  5. Dừng khi nhận SUCCESS, FAILURE hoặc FAIL.
  6. Sử dụng dữ liệu trong data khi thành công.

Important notes

  • data có cấu trúc khác nhau tùy loại task.
  • Không phải task nào cũng trả về progress hoặc estimated_time.
  • Hỗ trợ cả hai trạng thái lỗi FAILUREFAIL.
  • Không tiếp tục polling sau trạng thái cuối.
  • Không đặt polling interval quá ngắn.
  • Nên có timeout và cơ chế hủy ở phía client.
  • Khi request polling gặp lỗi mạng, có thể retry thay vì kết luận task thất bại.
  • Chỉ gọi Tasks API từ backend hoặc server được kiểm soát.
  • Không đưa API Key vào frontend hoặc mã nguồn công khai.