# API v2 JSON phản hồi và độ tin cậy

> Hiểu các trường meta và dữ liệu GenderAPI v2: giới tính, lý do không xác định, độ tin cậy, bằng chứng dữ liệu, điểm AI, chế độ truy cập và siêu dữ liệu thanh toán.

Canonical HTML: https://www.genderapi.io/vi/docs/v2/responses

Last reviewed: 2026-09-25

## Hiểu phản hồi JSON

Các phản hồi đơn thành công chứa data và meta. Phản hồi của tập dữ liệu bên dưới là một ví dụ minh họa, không phải là phép đo độ chính xác của sản phẩm hay lời hứa về kết quả trực tiếp tương tự. Nó hiển thị quyền truy cập thử nghiệm IP. Yêu cầu được xác thực bằng khóa tài khoản trả về access.mode: api_key; các trường chỉ áp dụng cho bản dùng thử có giá trị null.

| Trường | Ý nghĩa |
| --- | --- |
| data.input | Loại đầu vào, giá trị và quốc gia. forceToGenderize được bao gồm khi true. |
| data.name | Tên đã khớp hoặc được trích xuất; null khi không có sẵn. |
| data.gender | male, female hoặc JSON null. Đây là một dự đoán, không phải là bằng chứng về danh tính của một người. |
| data.result_status / reason | Khi result_status là identified, reason là null. Khi trạng thái là unknown, lý do là not_found, no_name_candidate, ambiguous hoặc insufficient_evidence. |
| data.confidence | Điểm 0–1 hoặc null. Giới tính không có độ tin cậy null. |
| data.confidence_kind | observed_frequency: số lượng giới tính chiếm ưu thế chia cho tổng số lượng trong tập dữ liệu đã chọn. model_reported: điểm AI, không phải xác suất được hiệu chỉnh. Giá trị là null khi không có sẵn. |
| data.sample_count | Kích thước mẫu tập dữ liệu hoặc null. AI không phát minh ra số lượng mẫu. |
| data.source | dataset, ai hoặc none. |
| data.country / country_source | Liên kết quốc gia từ tập dữ liệu hoặc ai_association hoặc null. Không xác định quốc tịch, nơi cư trú hoặc dân tộc. |
| data.match | Tên khớp trong tập dữ liệu, phương thức (normalized, token, substring hoặc model_inference), phạm vi (country hoặc global) và quốc gia tương ứng. Thông tin không có sẵn mang giá trị null. |
| meta.request_id / duration_ms | Mã định danh hoạt động và thời lượng xử lý tính bằng mili giây. |
| meta.access | Cách cấp quyền truy cập và lý do rút lại bản dùng thử, nếu có. |
| meta.usage | Phí ròng, số dư thời gian hoàn thành, trạng thái thanh toán và thông tin đặt lại bản dùng thử. |

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [Hoàn thành các lược đồ phản hồi và các ví dụ hàng loạt](https://api.genderapi.io/api/v2/openapi.json)

## Thành công không rõ kết quả

HTTP 200 có nghĩa là thao tác đã hoàn thành; nó không đảm bảo giới tính. Giữ nguyên JSON null thay vì chuyển đổi nó thành male, female, một chuỗi trống hoặc độ tin cậy bằng 0. Kiểm tra riêng data.result_status và data.reason với các lỗi HTTP.

Ví dụ chỉ có tập dữ liệu này trả về source: none và reason: not_found và vẫn tốn 1 tín dụng. Nếu số lượng tập dữ liệu cho hai giới tính bằng nhau thì kết quả có thể chứa reason: ambiguous trong khi vẫn giữ nguyên sample_count. Một kết quả AI không xác định sử dụng source: ai và reason: insufficient_evidence.

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "zzzxxyy",
      "country": null
    },
    "name": null,
    "gender": null,
    "country": null,
    "confidence": null,
    "confidence_kind": null,
    "sample_count": null,
    "source": "none",
    "result_status": "unknown",
    "reason": "not_found",
    "country_source": null,
    "match": {
      "name": null,
      "method": null,
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

## Giải thích sự tự tin và bằng chứng phù hợp

Độ tin cậy 0,9 nằm trên thang điểm 0–1. Đối với observed_frequency, nó có nghĩa là số lượng vượt trội chia cho tổng số tập dữ liệu đã chọn; nó không được đo lường độ chính xác của sản phẩm từ đầu đến cuối. Điểm model_reported do AI cung cấp và không được hiệu chỉnh theo tần số của tập dữ liệu.

Chọn bất kỳ ngưỡng ứng dụng nào bằng cách sử dụng dữ liệu đánh giá của riêng bạn và confidence_kind. Không trực tiếp xếp hạng tập dữ liệu và điểm AI như thể chúng đo lường cùng một thứ. AI match.name, match.scope và match.country là null vì không có hàng tập dữ liệu nào được chọn; match.method là model_inference.

Đối với tên đầy đủ, kết quả tập dữ liệu có thể đến từ một thành phần thay vì chuỗi đầy đủ. data.input giữ nguyên giá trị đã gửi; data.name mô tả tên được trả về và data.match mô tả ứng viên và phạm vi tra cứu.

## Hướng dẫn liên quan

- [Phản hồi hàng loạt và lỗi theo từng mục](https://www.genderapi.io/vi/docs/v2/batch#batch-response)
- [Trạng thái thanh toán và các khoản tín dụng còn lại](https://www.genderapi.io/vi/docs/v2/credits-and-usage)
- [Khả năng tương thích và thử lại phản hồi](https://www.genderapi.io/vi/docs/v2/errors-and-retries#retries)