Tác vụ bất đồng bộ

Một số thao tác của Felo trả về task_id ngay lập tức và hoàn tất ở chế độ nền. Mô hình chung ở mọi nơi: gửi, thăm dò, rồi lấy kết quả.

Hai nhóm tác vụ

Xuất PPTX là một thao tác bất đồng bộ riêng: POST /v2/ppts/{ppt_business_id}/export, sau đó GET /v2/ppts/{ppt_business_id}/export.

SuperAgent không phải API thăm dò. Nó trả về stream_key và dùng SSE; xem tham chiếu SuperAgent.

Vòng đời

1. Gửi. Gửi các tham số mô hình hoặc quy trình. Một lần gửi thành công trả về task_id và trạng thái ban đầu.
2. Thăm dò. Đọc endpoint tác vụ theo một khoảng thời gian. Hãy đặt khoảng thời gian và thời gian chờ tối đa trong mã của bạn.
3. Kết thúc. Khi thành công, đọc URL kết quả hoặc các trường đầu ra. Khi thất bại, đọc lỗi và quyết định có gửi lại hay không.

Giá trị trạng thái

Tác vụ quy trình Felo dùng giá trị chữ hoa:

Tác vụ tạo sinh mô hình dùng giá trị chữ thường: queued, running, succeeded, failed và interrupted. Một tác vụ thất bại có thể bao gồm đối tượng error với message và type.

Các giá trị trạng thái chưa biết có thể xuất hiện khi backend phát triển. Hãy coi giá trị chưa biết là chưa kết thúc trừ khi tài liệu nói khác.

Thăm dò trạng thái

• Tác vụ quy trình Felo: thăm dò mỗi 2–5 giây.
• Tạo video: thăm dò mỗi 5–10 giây.
• Tạo hình ảnh: bắt đầu với 2–5 giây và giãn dần cho các tác vụ chạy lâu.
• Dừng khi gặp trạng thái kết thúc, khi hết thời gian chờ bạn chọn, hoặc sau số lần thử tối đa.
• Thêm độ trễ ngẫu nhiên khi nhiều máy khách cùng thăm dò.

Một vòng lặp Node.js đơn giản:

async function pollStatus(taskId, { timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const response = await fetch(`https://openapi.felo.ai/v2/tasks/${taskId}/status`, {
      headers: { Authorization: `Bearer ${process.env.FELO_API_KEY}` },
    });
    if (!response.ok) throw new Error(`status ${response.status}`);
    const payload = await response.json();
    const status = payload.data?.status;
    if (status === "COMPLETED") return payload.data;
    if (["FAILED", "PENDING", "EXPIRED", "CANCELED"].includes(status)) {
      throw new Error(payload.data?.error_message || status);
    }
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
  throw new Error("task timed out");
}

Lấy kết quả

URL tải xuống đã ký của PPTX hết hạn 30 phút sau khi được cấp. Hãy gọi lại endpoint GET để lấy URL mới; việc này không tạo lại tệp.

Xử lý thất bại

• Đọc trường lỗi của tác vụ trước khi thử lại. Một số thất bại do yêu cầu gây ra và sẽ lặp lại.
• Không gửi lại một cách mù quáng mỗi khi hết thời gian chờ; trước tiên hãy kiểm tra xem tác vụ còn RUNNING hay không.
• 402 nghĩa là không đủ tín dụng. 429 nghĩa là bị giới hạn tần suất. Chỉ thử lại sau khi điều kiện đó được giải quyết.
• Các trường callback trên tạo video và hình ảnh hiện bị bỏ qua. Hãy thăm dò endpoint tác vụ thay vì chờ webhook.

Liên quan

• PPT Task API
• Landing Page Task API
• Tham chiếu Model API
• Tạo hình ảnh
• Lỗi, giới hạn và thử lại