API访问

管理您的API密钥并将VisaPics集成到您的应用程序中

API余额

加载中...

当前费率

$0.50/照片

您的级别

Base

充值

可用照片

已处理照片

活动密钥

速率限制

1,000/小时

您的API密钥

API文档

Loading API keys...

按需付费定价

存入越多，费率越优惠。等级基于终身存款总额。

Base

$0.50

每张照片

< $100 已充值

Starter

$0.40

每张照片

20% 折扣

$100+ 已充值

Professional

$0.30

每张照片

40% 折扣

$250+ 已充值

Enterprise

$0.20

每张照片

60% 折扣

$500+ 已充值

API参考

Swagger UI OpenAPI

身份验证

所有API请求都需要通过Bearer令牌进行身份验证：

Authorization: Bearer YOUR_API_KEY

GET /api/v1/specifications/{country_code} 获取文档规格

Returns all document types for a country with their spec_id.

Parameters

country_code string, required

ISO 2-letter country code (us, gb, de, etc.)

Example Response

{
  "specifications": [
    {"id": 822, "name": "US Passport", "type": "passport"},
    {"id": 821, "name": "US Visa", "type": "visa"}
  ]
}

POST /api/v1/photo/process 处理照片

Upload and process a photo. Returns task_id for async processing.

Request Body (multipart/form-data)

photo *

file

JPEG or PNG image file

spec_id *

integer

Document specification ID (get from /specifications endpoint)

output_format string

"url" (default) or "base64"

Example Request (cURL)

curl -X POST "https://visapics.org/api/v1/photo/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "photo=@photo.jpg" \
  -F "spec_id=822"

Response (202 Accepted)

{
  "status": "processing",
  "task_id": "abc123-def456-...",
  "message": "Photo queued for processing"
}

GET /api/v1/task/{task_id} 获取处理结果

Poll this endpoint to get the processing result.

States

PENDING - In queue

PROCESSING - Being processed

SUCCESS - Completed

FAILURE - Error occurred

Success Response

{
  "success": true,
  "data": {
    "state": "SUCCESS",
    "progress": 100,
    "result": {
      "specification": {
        "country_code": "us",
        "document_type": "US Passport"
      },
      "compliance": {
        "overall_success": true,
        "photo_size": "51x51mm",
        "head_measurements": "25-35mm",
        "resolution_dpi": 300,
        "warnings": [],
        "suitable_for_online": true,
        "printable": true
      },
      "digital_photo_url": "/download/...",
      "printable_photo_url": "/download_printable/..."
    }
  }
}

Error Response (Photo Failed)

{
  "success": false,
  "error": {
    "code": "E400_PROCESSING",
    "message": "Photo processing failed",
    "failure_reasons": [{
      "code": "NO_FACE_DETECTED",
      "message": "No face detected in the photo",
      "suggestion": "Upload a photo with a clearly visible face"
    }],
    "compliance_issues": ["Head size out of spec range"],
    "warnings": []
  }
}

GET /api/v1/billing/balance 获取账户余额

{
  "balance_usd": 25.50,
  "photos_available": 51,
  "tier": "Starter",
  "rate_per_photo": 0.40
}

失败原因代码

当照片处理失败时，这些代码说明原因：

NO_FACE_DETECTED

No face found in the uploaded photo

MULTIPLE_FACES

More than one face detected

HEAD_SIZE_INVALID

Head size cannot meet spec requirements

EYE_POSITION_INVALID

Eye position cannot be adjusted

LOW_RESOLUTION

Photo resolution too low

PROCESSING_FAILED

General processing error

完整代码示例

带异步轮询的完整示例：

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://visapics.org/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def process_photo(photo_path, spec_id):
    # Step 1: Upload photo
    with open(photo_path, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/photo/process",
            headers=HEADERS,
            files={"photo": f},
            data={"spec_id": spec_id}
        )

    task_id = response.json()["task_id"]
    print(f"Task created: {task_id}")

    # Step 2: Poll for result
    while True:
        result = requests.get(
            f"{BASE_URL}/task/{task_id}",
            headers=HEADERS
        ).json()

        if result["state"] == "SUCCESS":
            return result["result"]
        elif result["state"] == "FAILURE":
            raise Exception(result.get("error", "Processing failed"))

        time.sleep(1)  # Poll every second

# Usage
result = process_photo("photo.jpg", spec_id=822)
print(f"Photo URL: {result['photo_url']}")
print(f"Printable: {result['printable_url']}")

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://visapics.org/api/v1';

async function processPhoto(file, specId) {
    // Step 1: Upload photo
    const formData = new FormData();
    formData.append('photo', file);
    formData.append('spec_id', specId);

    const uploadRes = await fetch(`${BASE_URL}/photo/process`, {
        method: 'POST',
        headers: { 'Authorization': `Bearer ${API_KEY}` },
        body: formData
    });

    const { task_id } = await uploadRes.json();
    console.log('Task created:', task_id);

    // Step 2: Poll for result
    while (true) {
        const statusRes = await fetch(`${BASE_URL}/task/${task_id}`, {
            headers: { 'Authorization': `Bearer ${API_KEY}` }
        });
        const result = await statusRes.json();

        if (result.state === 'SUCCESS') {
            return result.result;
        } else if (result.state === 'FAILURE') {
            throw new Error(result.error || 'Processing failed');
        }

        await new Promise(r => setTimeout(r, 1000));
    }
}

// Usage
const result = await processPhoto(fileInput.files[0], 822);
console.log('Photo URL:', result.photo_url);

<?php
$API_KEY = 'YOUR_API_KEY';
$BASE_URL = 'https://visapics.org/api/v1';

function processPhoto($photoPath, $specId) {
    global $API_KEY, $BASE_URL;

    // Step 1: Upload photo
    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => "$BASE_URL/photo/process",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $API_KEY"],
        CURLOPT_POSTFIELDS => [
            'photo' => new CURLFile($photoPath),
            'spec_id' => $specId
        ]
    ]);
    $response = json_decode(curl_exec($curl), true);
    $taskId = $response['task_id'];

    // Step 2: Poll for result
    while (true) {
        curl_setopt($curl, CURLOPT_URL, "$BASE_URL/task/$taskId");
        curl_setopt($curl, CURLOPT_POST, false);
        curl_setopt($curl, CURLOPT_POSTFIELDS, null);
        $result = json_decode(curl_exec($curl), true);

        if ($result['state'] === 'SUCCESS') {
            return $result['result'];
        } elseif ($result['state'] === 'FAILURE') {
            throw new Exception($result['error'] ?? 'Failed');
        }
        sleep(1);
    }
}

// Usage
$result = processPhoto('photo.jpg', 822);
echo "Photo URL: " . $result['photo_url'];

# Step 1: Upload photo (returns task_id)
curl -X POST "https://visapics.org/api/v1/photo/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "photo=@photo.jpg" \
  -F "spec_id=822"

# Response: {"task_id": "abc123-def456-..."}

# Step 2: Poll for result (repeat until state is SUCCESS)
curl "https://visapics.org/api/v1/task/abc123-def456-..." \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response when done:
# {
#   "state": "SUCCESS",
#   "result": {
#     "photo_url": "https://visapics.org/processed/...",
#     "printable_url": "https://visapics.org/processed/...",
#     "preview_url": "https://visapics.org/previews/..."
#   }
# }

API访问

您的API密钥

按需付费定价

Base

Starter

Professional

Enterprise

API参考

身份验证

Parameters

Example Response

Request Body (multipart/form-data)

Example Request (cURL)

Response (202 Accepted)

States

Success Response

Error Response (Photo Failed)

失败原因代码

完整代码示例

Create API Key

API Key Created

Important

Revoke API Key

Warning