Tài liệu API

Mọi thứ AI của bạn — hoặc bạn — có thể gọi: chương trình nhà trường, bản quiz, hình, PDF, và tín hiệu đang làm việc.

Cách xác thực

Lời gọi quiz cần Authorization: Bearer cùng khóa quiz. Gửi If-Match với số phiên bản hiện tại để hai lần lưu không ghi đè nhau. Các phản hồi này không bao giờ được cache.

Mở schema đầy đủ

URL gốc

https://quiz.ai/api/v1

Cách xác thực

Authorization: Bearer <quiz-scoped-key>

Bản đồ API

GET
/api/v1

Bản đồ API và các liên kết theo sau.

Không cần khóa
GET
/api/v1/openapi.json

Toàn bộ schema OpenAPI 3.1 — tiện cho công cụ đọc được nó.

Không cần khóa

Chương trình nhà trường

GET
/api/v1/curricula

Liệt kê các chương trình nhà trường chúng tôi biết.

Không cần khóa
GET
/api/v1/curricula/{curriculumId}

Đọc chi tiết một chương trình.

Không cần khóa
GET
/api/v1/curricula/{curriculumId}/objectives?subject=math&grade=5&limit=100&offset=0

Tìm mục tiêu học tập theo môn và khối lớp.

Không cần khóa

Bản quiz

GET
/api/v1/target

Xem khóa này được phép ghi quiz nào.

Khóa quiz
GET
/api/v1/quizzes/{quizId}

Đọc quiz hiện tại và số phiên bản.

Khóa quiz
PUT
/api/v1/quizzes/{quizId}

Thay toàn bộ quiz trong một lần lưu. Gửi If-Match để không ghi đè việc mới hơn.

Khóa quiz
POST
/api/v1/quizzes/{quizId}/publish

Kiểm quiz và đưa ra công khai. Gửi If-Match để không ghi đè việc mới hơn.

Khóa quiz

Hình

POST
/api/v1/quizzes/{quizId}/images

Tải PNG, JPEG, GIF, hoặc WebP. Chúng tôi lưu một WebP tĩnh sạch.

Khóa quiz
POST
/api/v1/quizzes/{quizId}/images/templates

Vẽ hình câu hỏi từ mẫu, hoặc xem trước dạng PNG hoặc SVG.

Khóa quiz
GET
/api/v1/quizzes/{quizId}/images/{imageId}

Tải hình đã lưu. Hỗ trợ yêu cầu Range.

Khóa quiz
DELETE
/api/v1/quizzes/{quizId}/images/{imageId}

Xóa hình không câu nào đang dùng.

Khóa quiz
Hình câu hỏi

PDF và tín hiệu hoạt động

POST
/api/v1/quizzes/{quizId}/activity

Bắt đầu, làm mới, hoặc dừng tín hiệu “vẫn đang làm” 90 giây.

Khóa quiz
GET
/api/v1/quizzes/{quizId}/sheet.pdf?names=Alice,Bob&class=5B&key=0

Tải phiếu trả lời in được. Có thể thêm tên, lớp, và đáp án.

Khóa quiz

Lưu cả quiz

AI gửi tiêu đề, mô tả, ngôn ngữ, và mọi câu hỏi một lần. Gửi lại cùng quiz hợp lệ thì an toàn.

HTTP
PUT /api/v1/quizzes/qz_7KF2M9qTx3aB
Authorization: Bearer <quiz-scoped-key>
Content-Type: application/json
If-Match: "0"

{
  "title": "A quick tour of the Solar System",
  "description": "Ten friendly questions for curious adults.",
  "language": "en-gb",
  "questions": [
    {
      "prompt": "Which planet has the shortest year?",
      "choices": ["Mercury", "Venus", "Earth", "Mars"],
      "correctChoiceIndex": 0,
      "explanation": "Mercury orbits the Sun in about 88 Earth days."
    }
  ]
}

Quy tắc câu hỏi

  • Mỗi câu cần đề rõ và hai đến sáu lựa chọn không rỗng.
  • Giới hạn: tiêu đề 140 ký tự, mô tả 1.000, 1–100 câu, đề 500, mỗi lựa chọn 240, giải thích 1.000.
  • correctChoiceIndex là chỉ số bắt đầu từ 0 của lựa chọn đúng.
  • Thứ tự câu là thứ tự mảng — cái đầu danh sách là câu 1.
  • Gửi số phiên bản mới nhất trong header If-Match để hai lần lưu không đè nhau.

Đăng khi trông ổn

Đăng sẽ kiểm lại quiz và cho bạn liên kết công khai ổn định. Nếu thiếu gì, sửa, lưu lại, rồi đăng.

HTTP
POST /api/v1/quizzes/qz_7KF2M9qTx3aB/publish
Authorization: Bearer <quiz-scoped-key>
If-Match: "1"