คู่มือ

งานแบบอะซิงโครนัส

ส่งงานที่ใช้เวลานาน ติดตามสถานะ จัดการสถานะสุดท้าย และดึงผลลัพธ์

การดำเนินการบางอย่างของ Felo จะส่ง task_id กลับมาทันทีและทำงานเสร็จในเบื้องหลัง รูปแบบเหมือนกันทุกที่: ส่งคำขอ โพลสถานะ แล้วดึงผลลัพธ์

ตระกูลงานสองแบบ

ตระกูล	การส่งคำขอ	การโพล
เวิร์กโฟลว์ Felo	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
การสร้างด้วยโมเดล	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /api/v1/videos/generations/{task_id}`, `GET /api/v1/images/generations/{task_id}`

การส่งออก PPTX เป็นการดำเนินการอะซิงโครนัสแยกต่างหาก: POST /v2/ppts/{ppt_business_id}/export แล้วตามด้วย GET /v2/ppts/{ppt_business_id}/export

SuperAgent ไม่ใช่ API แบบโพลสถานะ แต่จะส่ง stream_key กลับมาและใช้ SSE ดูเอกสารอ้างอิง SuperAgent

วงจรชีวิต

ส่งคำขอ ส่งพารามิเตอร์ของโมเดลหรือเวิร์กโฟลว์ การส่งที่สำเร็จจะให้ task_id และสถานะเริ่มต้น
โพล อ่าน endpoint ของงานตามช่วงเวลาที่กำหนด ให้กำหนดช่วงเวลาและเวลารอสูงสุดไว้ในโค้ดของคุณ
สิ้นสุด เมื่อสำเร็จ ให้อ่าน URL ผลลัพธ์หรือฟิลด์เอาต์พุต เมื่อล้มเหลว ให้อ่านข้อผิดพลาดและตัดสินใจว่าจะส่งคำขอใหม่หรือไม่

ค่าสถานะ

งานเวิร์กโฟลว์ Felo ใช้ค่าตัวพิมพ์ใหญ่:

สถานะ	ความหมาย
`RUNNING`	กำลังประมวลผล
`COMPLETED`	เสร็จสมบูรณ์
`FAILED`	ล้มเหลวอย่างสิ้นสุด อ่าน `error_message`
`PENDING`	สถานะสิ้นสุดในการตอบกลับย้อนหลัง อ่าน `error_message`
`EXPIRED`	สิ้นสุด งานไม่พร้อมใช้งานแล้ว
`CANCELED`	สิ้นสุด งานถูกยกเลิก

งานสร้างด้วยโมเดลใช้ค่าตัวพิมพ์เล็ก: queued, running, succeeded, failed และ interrupted งานที่ล้มเหลวอาจมีออบเจกต์ error พร้อม message และ type

ค่าสถานะที่ไม่รู้จักอาจปรากฏขึ้นเมื่อระบบเบื้องหลังพัฒนาต่อ ให้ถือว่าค่าที่ไม่รู้จักยังไม่สิ้นสุด เว้นแต่เอกสารจะระบุไว้เป็นอย่างอื่น

การโพล

งานเวิร์กโฟลว์ Felo: โพลทุก 2–5 วินาที
การสร้างวิดีโอ: โพลทุก 5–10 วินาที
การสร้างรูปภาพ: เริ่มที่ 2–5 วินาทีและเพิ่มช่วงเวลาสำหรับงานที่ใช้เวลานาน
หยุดเมื่อถึงสถานะสิ้นสุด เมื่อถึงเวลาหมดเวลาที่คุณกำหนด หรือหลังจากจำนวนครั้งสูงสุด
เพิ่ม jitter เมื่อมีไคลเอนต์จำนวนมากโพลพร้อมกัน

ลูป Node.js อย่างง่าย:

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");
}

ดึงผลลัพธ์

งาน	ผลลัพธ์
PPT	`GET /v2/tasks/{task_id}/historical` ส่ง `ppt_url`, `ppt_biz_id` และ `live_doc_url` เมื่อมี
หน้าแลนดิ้ง	การตอบกลับย้อนหลังส่งเอาต์พุตของหน้าและ `live_doc_url` เมื่อมี
วิดีโอ / รูปภาพ	การตอบกลับจากการโพลส่ง `outputs` เมื่อสำเร็จ รายการจะเป็น URL สื่อที่ลงนามแล้วซึ่งดาวน์โหลดได้โดยไม่ระบุตัวตน ดูการสร้างรูปภาพสำหรับรายละเอียดการหมดอายุและการดาวน์โหลด
การส่งออก PPTX	การตอบกลับจากการโพลส่ง `download_url` และ `expires_at` เฉพาะเมื่อ `status` เป็น `COMPLETED`

URL ดาวน์โหลดที่ลงนามแล้วของ PPTX จะหมดอายุ 30 นาทีหลังออก ให้เรียก endpoint GET อีกครั้งเพื่อรับ URL ใหม่ ซึ่งจะไม่สร้างไฟล์ใหม่

การจัดการความล้มเหลว

อ่านฟิลด์ข้อผิดพลาดของงานก่อนลองใหม่ ความล้มเหลวบางอย่างเกิดจากคำขอและจะเกิดซ้ำ
ห้ามส่งคำขอใหม่โดยไม่ตรวจสอบทุกครั้งที่หมดเวลา ให้ตรวจสอบก่อนว่างานยังเป็น RUNNING อยู่หรือไม่
402 หมายถึงเครดิตไม่เพียงพอ 429 หมายถึงติดขีดจำกัดอัตรา ให้ลองใหม่หลังเงื่อนไขนั้นคลี่คลายแล้ว
ฟิลด์ callback ในการสร้างวิดีโอและรูปภาพถูกเพิกเฉยในปัจจุบัน ให้โพล endpoint ของงานแทนการรอ webhook