ناوبری سریع

APIهای مرتبط

Bank Card OCR API

این API تصویر کارت بانکی را دریافت کرده و شماره …

National Card OCR API

این API تصویر کارت ملی را دریافت کرده و اطلاعات …

Video Authentication API

این API ویدیو احراز هویت کاربر را دریافت کرده و …

Mobile National Code Match API

This API endpoint allows you to verify if a mobile …

National Code Birthday Match API

This API verifies whether an Iranian national code matches a …

Selfie National Code Birthday Match API

این API تصویر سلفی کاربر را به همراه کد ملی …

POST احراز هویت

Compare Images API

این API دو تصویر چهره را دریافت می‌کند و آن‌ها را با یکدیگر تطبیق می‌دهد. در صورت موفقیت، نتیجه تطبیق به همراه میزان شباهت برگردانده شده و هزینه سرویس از کیف پول کسر می‌شود.

POST /api/services/compare-images/

نیاز به احراز هویت Token 30 requests/minute

مستندات

Overview

The Compare Images API accepts two face images and compares them to determine if they belong to the same person using Sepal Yar's face comparison services. The API returns a similarity score and verification result.

Authentication

Provide token authentication headers in every request:

Authorization: Token YOUR_AUTH_TOKEN
X-Unique-Code: YOUR_UNIQUE_CODE

Request Format

Send a POST request with multipart/form-data body containing two face images:

curl -X POST /api/services/compare-images/ \
  -H "Authorization: Token ..." \
  -H "X-Unique-Code: ..." \
  -F "image1=@face1.jpg;type=image/jpeg" \
  -F "image2=@face2.jpg;type=image/jpeg"

Response Format

در پاسخ موفق، کلید response_data حاوی نتیجه تطبیق است. فیلد verified نشان می‌دهد تطبیق موفق بوده است یا خیر و similarity میزان شباهت دو چهره را نشان می‌دهد (مقدار بین ۰ تا ۱). همچنین شناسه رهگیری در ref_id و زمان عملیات در operation_time بازگردانده می‌شود.

Best Practices

Use high-quality face images with good lighting and full face visible.
Ensure both images are clear and show the same person from similar angles.
Store request_ref, ref_id and operation_time for auditing.
Consider the similarity threshold based on your use case (typically 0.7-0.9).

پارامترهای درخواست

پارامتر	نوع	اجباری	توضیحات	مثال
`image1`	File	اجباری	تصویر اول چهره (حداکثر حجم ۳ مگابایت، فرمت‌های مجاز: JPG، PNG). اعتبارسنجی: حداکثر حجم ۳ مگابایت. تصویر باید واضح باشد و چهره کامل دیده شود.	`face1.jpg`
`image2`	File	اجباری	تصویر دوم چهره (حداکثر حجم ۳ مگابایت، فرمت‌های مجاز: JPG، PNG). اعتبارسنجی: حداکثر حجم ۳ مگابایت. تصویر باید واضح باشد و چهره کامل دیده شود.	`face2.jpg`

مثال‌های کد

Python Example

Example using Python requests library.

import requests

url = "https://inquiry.sepal.ir/api/services/compare-images/"
headers = {
    "Authorization": "Token YOUR_AUTH_TOKEN",
    "X-Unique-Code": "YOUR_UNIQUE_CODE",
}
files = {
    "image1": ("face1.jpg", open("face1.jpg", "rb"), "image/jpeg"),
    "image2": ("face2.jpg", open("face2.jpg", "rb"), "image/jpeg"),
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

C# Example

Example using C# HttpClient with multipart/form-data.

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.IO;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", "YOUR_AUTH_TOKEN");
        client.DefaultRequestHeaders.Add("X-Unique-Code", "YOUR_UNIQUE_CODE");

        using var form = new MultipartFormDataContent();
        
        using var fileStream1 = File.OpenRead("face1.jpg");
        var fileContent1 = new StreamContent(fileStream1);
        fileContent1.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        form.Add(fileContent1, "image1", "face1.jpg");

        using var fileStream2 = File.OpenRead("face2.jpg");
        var fileContent2 = new StreamContent(fileStream2);
        fileContent2.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        form.Add(fileContent2, "image2", "face2.jpg");

        var response = await client.PostAsync("https://inquiry.sepal.ir/api/services/compare-images/", form);
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

PHP Example

Example using PHP cURL file upload.

<?php

$url = "https://inquiry.sepal.ir/api/services/compare-images/";

$headers = [
    "Authorization: Token YOUR_AUTH_TOKEN",
    "X-Unique-Code: YOUR_UNIQUE_CODE"
];

$postFields = [
    "image1" => new CURLFile("face1.jpg", "image/jpeg", "face1.jpg"),
    "image2" => new CURLFile("face2.jpg", "image/jpeg", "face2.jpg")
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

cURL Example

Command-line cURL example.

curl -X POST "https://inquiry.sepal.ir/api/services/compare-images/" \
  -H "Authorization: Token YOUR_AUTH_TOKEN" \
  -H "X-Unique-Code: YOUR_UNIQUE_CODE" \
  -F "image1=@face1.jpg;type=image/jpeg" \
  -F "image2=@face2.jpg;type=image/jpeg"

فرمت پاسخ

200

پاسخ موفق

پاسخ موفق شامل نتیجه تطبیق دو چهره و میزان شباهت.

ساختار پاسخ:

{
  "amount": "integer",
  "success": "boolean",
  "request_ref": "string",
  "error_message": "null",
  "response_data": {
    "ref_id": "string",
    "verified": "boolean",
    "similarity": "float",
    "operation_time": "integer"
  },
  "response_time_ms": "integer"
}

مثال پاسخ:

{
  "amount": 20000,
  "success": true,
  "request_ref": "XIHAUOLARKN7M0KLZKJTRNTNIPXUL7YZ",
  "error_message": null,
  "response_data": {
    "ref_id": "test-ref-id-123",
    "verified": true,
    "similarity": 0.95,
    "operation_time": 1763287828519
  },
  "response_time_ms": 2100
}

400

خطا

پارامترهای ورودی نامعتبر هستند یا تصاویر ارسال نشده‌اند.

ساختار پاسخ:

{
  "error": {
    "errors": "list",
    "ref_id": "string",
    "operation_time": "integer"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "details": {
      "image1": [
        "This field is required."
      ]
    },
    "message": "پارامترهای ورودی نامعتبر است."
  },
  "success": false
}

422

خطا

تصاویر توسط سپال‌یار قابل پردازش نیست (کیفیت پایین، ناقص یا نامعتبر).

ساختار پاسخ:

{
  "error": {
    "errors": "list",
    "ref_id": "string",
    "operation_time": "integer"
  },
  "success": "boolean"
}

مثال پاسخ:

{
  "error": {
    "errors": [
      {
        "code": "5001",
        "message": "تصویر نامعتبر است."
      }
    ],
    "ref_id": "7713c9e3-0b54-4a72-8a01-17fb37ee0ede",
    "operation_time": 1762691215312
  },
  "success": false
}