Trình khám phá API Tương tác

1. Xác thực (Authentication)

Để tương tác với API, bạn cần có một Access Token. Token này phải được gửi kèm trong mỗi yêu cầu ở phần header Authorization.

• Header: Authorization
• Value: Bearer <YOUR_ACCESS_TOKEN>

2. Endpoint API

Tất cả các yêu cầu cần được gửi đến endpoint sau đây qua phương thức POST:

https://avoca.dify.host/v1/workflows/run

3. Ví dụ với cURL

curl -X POST 'https://avoca.dify.host/v1/workflows/run' \\
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\
-H 'Content-Type: application/json' \\
-d '{
    "inputs": {
        "assignment": "Write about your last summer vacation.",
        "student_writing": "My last summer vacation was very fun...",
        "methodology": "Traditional",
        "grade": 7
    },
    "response_mode": "blocking",
    "user": "user-12345"
}'

Cấu trúc Đầu vào (Input)

/**
 * Định nghĩa cấu trúc đầy đủ của body khi gọi API.
 */
interface APIRequestPayload {
  inputs: {
    assignment: string;
    student_writing: string;
    methodology: "Traditional" | "Bloom Taxonomy";
    grade: number;
  };
  response_mode: "blocking" | "streaming";
  user: string;
}

Cấu trúc Đầu ra: Bloom Taxonomy

interface BloomAssessmentOutput {
  summary: string;
  score: string;
  assessment: {
    criteria: string;
    score: number;
    assessment: string;
    evidences: string[];
    justification: string;
  }[];
}

Cấu trúc Đầu ra: Traditional

interface TraditionalAssessmentOutput {
  overall: string;
  level_consistency: number;
  justification: {
    vocabulary: string;
    grammar: string;
    rhetorical: string;
  };
  errors: {
    evidences: string;
    correction: string;
    justification: string;
  }[];
  metrics: {
    task_achievement: MetricItem;
    cohesion_and_coherance: MetricItem;
    lexical: MetricItem;
    grammar_accuracy: MetricItem;
  };
  recommendation: {
    strengths: string[];
    need_improvements: string[];
    actions: string[];
  };
}

interface MetricItem {
  score: number;
  justification: string;
  evidences: string[];
}