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
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | string | Yes | ID đượ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
| Status | Meaning | Action |
|---|---|---|
PENDING | Tác vụ đang chờ được xử lý | Tiếp tục polling |
PROCESSING | Tác vụ đang được xử lý | Tiếp tục polling |
SUCCESS | Tác vụ đã hoàn tất | Đọc kết quả trong data và dừng polling |
FAILURE | Tác vụ thất bại | Đọc thông tin lỗi và dừng polling |
FAIL | Tác vụ thất bại | Xử lý tương tự FAILURE |
Tích hợp nên hỗ trợ cả FAILURE và FAIL.
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
| Field | Type | Description |
|---|---|---|
status | "PENDING" | "PROCESSING" | Trạng thái hiện tại của tác vụ |
step | string | Bước xử lý hiện tại, nếu có |
progress | number | Tiến độ ước tính từ 0 đến 100 |
estimated_time | number | Thờ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
| Field | Type | Description |
|---|---|---|
data.note_id | string | ID của note được tạo hoặc cập nhật |
data.title | string | Tiêu đề của nội dung |
data.summary | string | Nội dung tóm tắt, nếu có |
data.type | string | Loại kết quả được tạo |
data.audio_url | string | URL file âm thanh, nếu tác vụ tạo audio |
data.youtube_url | string | URL YouTube nguồn, nếu có |
data.views | string | Thông tin lượt xem, nếu có |
message | string | Thô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 note | note_id, title, summary |
| Flashcards | Thông tin bộ flashcards |
| Quiz | Thông tin bộ câu hỏi |
| Mindmap | Dữ liệu hoặc URL mindmap |
| Slide | Thông tin bộ slide |
| Podcast | audio_url và metadata |
| Translate | Nộ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
| Field | Type | Description |
|---|---|---|
status | "FAILURE" | "FAIL" | Trạng thái thất bại |
error | string | Nội dung lỗi ngắn |
error_key | string | Mã lỗi ổn định để xử lý trong code |
message | string | Mô 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.
| Setting | Recommendation |
|---|---|
| Polling interval | Mỗi 3–5 giây |
| Stop condition | SUCCESS, FAILURE hoặc FAIL |
| Timeout | Tự thiết lập theo loại tác vụ |
| Cancellation | Hỗ 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à:
- Gọi API tạo nội dung.
- Lưu
task_id. - Poll Tasks API mỗi 3–5 giây.
- Hiển thị tiến độ nếu response có
stephoặcprogress. - Dừng khi nhận
SUCCESS,FAILUREhoặcFAIL. - Sử dụng dữ liệu trong
datakhi thành công.
Important notes
datacó cấu trúc khác nhau tùy loại task.- Không phải task nào cũng trả về
progresshoặcestimated_time. - Hỗ trợ cả hai trạng thái lỗi
FAILUREvàFAIL. - 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.