Đến nội dung
GFlow4AI
ENTải cho Windows
Hướng dẫn/Kết nối AI agent

Tham chiếu REST API

Tham chiếu kỹ thuậtCập nhật 2026-11-04Thử bản mẫu trên web

Tra cứu route thật, xác thực cục bộ, gửi chống trùng và tải kết quả của khoá.

Địa chỉ API nội bộ
Địa chỉ API nội bộ · Ảnh chụp app thật, dữ liệu mẫu

Trước khi bắt đầu

  • Dùng script hoặc HTTP client cùng PC, không dùng trang web hay connector cloud.
  • Bật máy chủ desktop và chuẩn bị khoá có đủ quyền cho quy trình.

Các bước

  1. Kiểm tra tình trạng và schema hiện tại

    Dùng URL gốc hiện tại trong Cài đặt. GET /v1/health và GET /v1/openapi.json không cần khoá nhưng vẫn kiểm Origin/Host. Các route REST còn lại bên dưới cần khoá Bearer.

    curl.exe http://127.0.0.1:47831/v1/status -H "Authorization: Bearer <your local API key>"

  2. Chỉ dùng route đã triển khai

    • GET /v1/health — tình trạng máy chủ, không cần khoá.
    • GET /v1/openapi.json — OpenAPI 3.1, không cần khoá.
    • GET /v1/status
    • GET /v1/models
    • GET /v1/voices
    • GET /v1/characters
    • POST /v1/characters
    • PATCH /v1/characters/{id}
    • POST /v1/references
    • POST /v1/jobs
    • GET /v1/jobs
    • GET /v1/jobs/{id}
    • GET /v1/jobs/{id}/wait
    • POST /v1/jobs/{id}/cancel
    • POST /v1/outputs/{id}/extend
    • POST /v1/outputs/{id}/edit
    • POST /v1/outputs/{id}/upscale
    • GET /v1/outputs/{id}/content
    • HEAD /v1/outputs/{id}/content

    Thay {id} bằng mã nhân vật, việc hoặc đầu ra tương ứng. Thao tác đọc cần read; tải tham chiếu, gửi/huỷ việc và thao tác tiếp theo trên đầu ra cần generate; ghi nhân vật cần characters. /mcp là giao thức MCP riêng, không phải thao tác REST.

  3. Chuẩn bị tham chiếu và gửi một lần

    Đọc /v1/models trước khi chọn model và lấy trường tạo việc từ OpenAPI. Gửi JSON với Content-Type: application/json. POST /v1/jobs và thao tác extend/edit/upscale yêu cầu Idempotency-Key (1–200 ký tự ASCII hiển thị được). Giữ nguyên khoá và thân yêu cầu khi thử lại: gửi lại nhận đúng việc cũ, còn cùng khoá nhưng khác nội dung trả 409. Việc mới trả 201; yêu cầu phát lại trả 200 kèm idempotent-replayed: true.

    Tải tham chiếu dưới dạng byte media trực tiếp tới /v1/references, không gửi đường dẫn tệp trong JSON. Video cần X-Rights-Confirmed: true; X-File-Name tuỳ chọn dùng để đặt tên.

  4. Chờ, phân trang và tải về

    Dùng GET /v1/jobs/{id}/wait?timeout=50; thời gian được chặn trong khoảng 0–50 giây (mặc định 30). Xem x-wait-result và việc trả về; hết thời gian chờ không phải việc thất bại. Tiếp tục chờ cùng việc tới done, failed hoặc cancelled.

    GET /v1/jobs?limit=20&cursor=… trả việc mới nhất trước với nextCursor; mỗi trang tối đa 100 việc. Tải đầu ra của khoá bằng GET content; HEAD đọc header và có hỗ trợ một khoảng byte.

  5. Xử lý lỗi mà không tiêu trùng

    Lỗi REST dùng application/problem+json với code, detail và có thể có errors theo trường. Phân biệt 401 khoá, 403 quyền/Origin, 404 không thuộc khoá hoặc không tồn tại, 409 xung đột, 422 dữ liệu sai và 429 giới hạn tốc độ/trần. Tuân theo Retry-After khi quá tốc độ. Không tạo việc thay thế chỉ vì chờ hoặc tải về thất bại.

Khi đã xong

Client đọc schema, gửi một việc có chống trùng, chờ theo mã rồi tải đầu ra thuộc khoá.

Nếu gặp trục trặc

Vì sao thấy việc trong app nhưng khoá gọi lại trả 404?

Khoá chỉ truy cập việc, đầu ra và tham chiếu của chính nó, không phải việc tạo từ giao diện hoặc tài nguyên của khoá khác.

Vì sao thử lại trả 409?

Kiểm tra mã lỗi. idempotency_conflict nghĩa là dùng lại mã chống trùng với nội dung khác; khôi phục yêu cầu gốc thay vì đổi mã mới một cách máy móc.