REST API · v1

Tek API çağrısıyla kurallara uygun vesikalık fotoğraflar

Bir fotoğrafı ve hangi belge için olduğunu gönderin. Fotoğraf, o belgenin resmî kurallarına göre kırpılmış, boyutlandırılmış ve kontrol edilmiş olarak her kontrolün sonucuyla geri gelir — kendi sitemizdeki motorun aynısı; uygulamalar, baskı merkezleri ve kiosklar için.

Test anahtarı alın Referansı okuyun

Temel URL https://api.takiphoto.com/api/v1

API durumu: Kontrol ediliyor…

Hızlı başlangıç

Sıfırdan bitmiş bir fotoğrafa üç adımda.

Test anahtarı alın
Bir API hesabı açın ve bir test anahtarı oluşturun — pk_test_ ile başlar. Test anahtarları ücretsizdir ve filigranlı bir önizleme döndürür.
Test anahtarı alın

Fotoğraf gönderin

Fotoğrafı ihtiyacınız olan belgeyle birlikte POST edin. Yanıt, fotoğraf hazır olur olmaz gelir; ya da takip etmeniz için Location başlığıyla 202 olarak döner.

curl -X POST "https://api.takiphoto.com/api/v1/photos" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000" \
  -F "[email protected]" \
  -F "spec_id=us-passport" \
  -F 'outputs=["digital"]'

Sonucu okuyun

Fotoğraf; durumunu, ölçüldüğü her kontrolü ve tamamlandığında dosyalarının imzalı bağlantılarını taşır. Biçimi şöyledir:

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

Kod örnekleri

Aynı üç çağrı dört dilde. Örnek anahtarı kendi anahtarınızla değiştirin.

Fotoğraf dosyası yükleme

curl -X POST "https://api.takiphoto.com/api/v1/photos" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000" \
  -F "[email protected]" \
  -F "spec_id=us-passport" \
  -F 'outputs=["digital"]'

Fotoğrafı geri okuma

curl "https://api.takiphoto.com/api/v1/photos/PHOTO_ID" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000"

Fotoğrafı URL'siyle gönderme

curl -X POST "https://api.takiphoto.com/api/v1/photos" \
  -H "Authorization: Bearer pk_test_EXAMPLE000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"spec_id": "us-passport", "image_url": "https://example.com/photo.jpg", "outputs": ["digital"]}'

Fotoğraf dosyası yükleme

import requests

with open("photo.jpg", "rb") as photo:
    response = requests.post(
        "https://api.takiphoto.com/api/v1/photos",
        headers={"Authorization": "Bearer pk_test_EXAMPLE000000000000000000000000000000000000"},
        files={"file": photo},
        data={"spec_id": "us-passport", "outputs": '["digital"]'},
        timeout=30,
    )
response.raise_for_status()
print(response.json()["status"])

Fotoğrafı geri okuma

import requests

response = requests.get(
    "https://api.takiphoto.com/api/v1/photos/PHOTO_ID",
    headers={"Authorization": "Bearer pk_test_EXAMPLE000000000000000000000000000000000000"},
    timeout=30,
)
photo = response.json()
print(photo["status"], photo["outputs"])

Fotoğrafı URL'siyle gönderme

import requests

response = requests.post(
    "https://api.takiphoto.com/api/v1/photos",
    headers={"Authorization": "Bearer pk_test_EXAMPLE000000000000000000000000000000000000"},
    json={"spec_id": "us-passport", "image_url": "https://example.com/photo.jpg", "outputs": ["digital"]},
    timeout=30,
)
print(response.json()["status"])

Fotoğraf dosyası yükleme

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg");
form.append("spec_id", "us-passport");
form.append("outputs", JSON.stringify(["digital"]));

const response = await fetch("https://api.takiphoto.com/api/v1/photos", {
  method: "POST",
  headers: { Authorization: "Bearer pk_test_EXAMPLE000000000000000000000000000000000000" },
  body: form,
});
const photo = await response.json();
console.log(photo.status);

Fotoğrafı geri okuma

const response = await fetch("https://api.takiphoto.com/api/v1/photos/PHOTO_ID", {
  headers: { Authorization: "Bearer pk_test_EXAMPLE000000000000000000000000000000000000" },
});
const photo = await response.json();
console.log(photo.status, photo.outputs);

Fotoğrafı URL'siyle gönderme

const response = await fetch("https://api.takiphoto.com/api/v1/photos", {
  method: "POST",
  headers: { Authorization: "Bearer pk_test_EXAMPLE000000000000000000000000000000000000", "Content-Type": "application/json" },
  body: JSON.stringify({ spec_id: "us-passport", image_url: "https://example.com/photo.jpg", outputs: ["digital"] }),
});
const photo = await response.json();
console.log(photo.status);

Fotoğraf dosyası yükleme

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final request = http.MultipartRequest('POST', Uri.parse('https://api.takiphoto.com/api/v1/photos'))
    ..headers['Authorization'] = 'Bearer pk_test_EXAMPLE000000000000000000000000000000000000'
    ..fields['spec_id'] = 'us-passport'
    ..fields['outputs'] = jsonEncode(['digital'])
    ..files.add(await http.MultipartFile.fromPath('file', 'photo.jpg'));
  final response = await http.Response.fromStream(await request.send());
  final photo = jsonDecode(response.body) as Map<String, dynamic>;
  print(photo['status']);
}

Fotoğrafı geri okuma

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final response = await http.get(
    Uri.parse('https://api.takiphoto.com/api/v1/photos/PHOTO_ID'),
    headers: {'Authorization': 'Bearer pk_test_EXAMPLE000000000000000000000000000000000000'},
  );
  final photo = jsonDecode(response.body) as Map<String, dynamic>;
  print(photo['status']);
}

Fotoğrafı URL'siyle gönderme

import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final response = await http.post(
    Uri.parse('https://api.takiphoto.com/api/v1/photos'),
    headers: {'Authorization': 'Bearer pk_test_EXAMPLE000000000000000000000000000000000000', 'Content-Type': 'application/json'},
    body: jsonEncode({'spec_id': 'us-passport', 'image_url': 'https://example.com/photo.jpg', 'outputs': ['digital']}),
  );
  print(jsonDecode(response.body)['status']);
}

API referansı

Yayımlanan OpenAPI sözleşmesinden üretilir; bu yüzden API'nin tam olarak neye yanıt verdiğini listeler — ne eksik ne fazla.

Her çağrı API anahtarınızı Authorization: Bearer pk_test_… başlığında taşır. Canlı anahtarlar (pk_live_) planınızdan düşer; test anahtarları (pk_test_) ücretsizdir ve sonuca filigran ekler.

`/photos`

post/photosAPI anahtarı

Create Photo

A photo from file (multipart) or image_url (JSON). Answers 200 with the result when the photo settles within the wait — completed (one credit on a live key), needs_retake or failed (free) — else 202 with Location to poll. An expert review answers 202 in_review until the expert decides.

İstek gövdesi `application/json`

backgroundstring | null

#RRGGBB; the document's own colour when absent.

Sınırlar:pattern: ^#[0-9A-Fa-f]{6}$

callback_urlstring | null

A public https URL told when this photo settles.

Sınırlar:maxLength: 512

expert_reviewboolean

Live keys: have an expert check the photo (one review credit).

Varsayılan: false

image_urlstring | nullzorunlu

JSON body only: a public http(s) URL of the photo, fetched by us (≤ 25 MB).

Sınırlar:maxLength: 2048

outputsarray<string>

The files wanted: the digital photo and any print sheets.

Şunlardan biri:digital4x6in10x15cma4

Sınırlar:minItems: 1maxItems: 4

retouchboolean

The automatic light retouch, when it is offered.

Varsayılan: false

spec_idstringzorunlu

A document from GET /specs.

Sınırlar:minLength: 4maxLength: 64

Örnek

{
  "background": "string",
  "callback_url": "string",
  "expert_review": false,
  "image_url": "string",
  "outputs": [
    "digital"
  ],
  "retouch": false,
  "spec_id": "string"
}

İstek gövdesi `multipart/form-data`

backgroundstring | null: #RRGGBB; the document's own colour when absent.
Sınırlar:pattern: ^#[0-9A-Fa-f]{6}$
callback_urlstring | null: A public https URL told when this photo settles.
Sınırlar:maxLength: 512
expert_reviewboolean: Live keys: have an expert check the photo (one review credit).
Varsayılan: false
filestring<binary>zorunlu: The photo: JPEG, PNG, HEIC or WebP, at most 25 MB.
outputsstring: The files wanted, as the JSON text of an array: ["digital","4x6in"].
Varsayılan: ["digital"]
retouchboolean: The automatic light retouch, when it is offered.
Varsayılan: false
spec_idstringzorunlu: A document from GET /specs.
Sınırlar:minLength: 4maxLength: 64

Yanıtlar

200Successful Response
202Still processing after `api.sync_wait_s` (15 s): follow `Location`.

Örnek

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/photos/{photo_id}`

get/photos/{photo_id}API anahtarı

Get Photo

The photo as it is now. Under the key's delete_after_download, the first read of a finished photo leaves it one more hour.

Parametreler

photo_idstringyoldazorunlu

Yanıtlar

200Successful Response

Örnek

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

delete/photos/{photo_id}API anahtarı

Delete Photo

The photo and every file made from it, at once.

Parametreler

photo_idstringyoldazorunlu

Yanıtlar

- 204Successful Response
- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/photos/{photo_id}/adjust`

post/photos/{photo_id}/adjustAPI anahtarı

Adjust Photo

Scale and shift the crop (the same rules as the web editor); the photo's files are made again at once. Free: credits_charged does not change.

Parametreler

photo_idstringyoldazorunlu

İstek gövdesi `application/json`

dxnumberzorunlu: Sınırlar:minimum: -300maximum: 300
dynumberzorunlu: Sınırlar:minimum: -300maximum: 300
scalenumberzorunlu: Sınırlar:minimum: 0.7maximum: 1.4

Örnek

{
  "dx": 0,
  "dy": 0,
  "scale": 0.7
}

Yanıtlar

200Successful Response

Örnek

{
  "checks": [
    {
      "code": "string",
      "hint": "string",
      "result": "string",
      "value": 0
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "credits_charged": 0,
  "crop": {
    "rotation_deg": 0,
    "scale": 0,
    "x0": 0,
    "x1": 0,
    "y0": 0,
    "y1": 0
  },
  "expires_at": "2026-01-01T12:00:00Z",
  "id": "string",
  "outputs": {
    "digital": {
      "bytes": 0,
      "height": 0,
      "url": "string",
      "width": 0
    },
    "sheets": {
      "key": {
        "jpeg": "string",
        "pdf": "string"
      }
    }
  },
  "review": {
    "reason": "string",
    "status": "string"
  },
  "spec": {
    "id": "string",
    "version": 0
  },
  "status": "processing"
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/specs`

get/specsAPI anahtarı

List Specs

The document specs a photo can be made for, verified ones first; country is the ISO 3166-1 alpha-2 code, q matches the id or a name in any language.

Parametreler

countrystring | nullsorguda

Sınırlar:minLength: 2maxLength: 2

qstring | nullsorguda

Sınırlar:maxLength: 64

limitintegersorguda

Varsayılan: 50

Sınırlar:minimum: 1maximum: 200

Yanıtlar

200Successful Response

Örnek

[
  {
    "background": "string",
    "category": "string",
    "country": "string",
    "id": "string",
    "names": {
      "key": "string"
    },
    "output_px": [
      0
    ],
    "tier": "string",
    "version": 0
  }
]

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/specs/{spec_id}`

get/specs/{spec_id}API anahtarı

Get Spec

Parametreler

spec_idstringyoldazorunlu

Yanıtlar

200Successful Response

Örnek

{
  "allowed_backgrounds": [
    "string"
  ],
  "background": "string",
  "category": "string",
  "country": "string",
  "digital": {
    "format": "string",
    "height_px": 0,
    "max_kb": 0,
    "max_px": 0,
    "min_px": 0,
    "width_px": 0
  },
  "dpi": 0,
  "eye_line_from_bottom_mm": {
    "max": 0,
    "min": 0
  },
  "head_height_mm": {
    "max": 0,
    "min": 0
  },
  "id": "string",
  "names": {
    "key": "string"
  },
  "output_px": [
    0
  ],
  "print_sheets": [
    "string"
  ],
  "rules": {
    "color": "string",
    "expression": "string",
    "glasses": "string",
    "head_covering": "string"
  },
  "size_mm": {
    "height": 0,
    "width": 0
  },
  "source_url": "string",
  "tier": "string",
  "verified_at": "2026-01-01",
  "version": 0
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

`/usage`

get/usageAPI anahtarı

Usage

Credits left this period, the key's rate limit and mode, and its calls today.

Yanıtlar

200Successful Response

Örnek

{
  "mode": "live",
  "period_end": "2026-01-01T12:00:00Z",
  "photos": {
    "balance": 0,
    "quota": 0,
    "used_this_period": 0
  },
  "rate_limit_per_min": 0,
  "requests_today": 0,
  "reviews": {
    "balance": 0,
    "quota": 0,
    "used_this_period": 0
  }
}

- 400Invalid request
- 401Authentication required
- 402Quota used up
- 403Not allowed
- 404Not found
- 413Upload too large
- 422Request is not valid
- 429Rate limited
- 503Maintenance
Örnek
```
{
  "code": "string",
  "hint": "string",
  "message": "string"
}
```

Kontrol ve hata kodları

API'nin döndürebileceği her kod; kendi uygulamalarımızın çevirdiği listenin aynısı.

Kontrol kodları

Bir fotoğrafın kontrollerindeki her öğe, bu kodlardan birini sonucuyla birlikte verir.

Kod	Anlamı
`file_invalid`	Bu dosyayı okuyamadık JPEG, PNG veya HEIC formatında bir fotoğraf yükleyin.
`file_too_large`	Dosya çok büyük Daha küçük bir kopya dışa aktarıp tekrar deneyin.
`image_too_large`	Görüntünün piksel sayısı çok yüksek 50 megapiksele kadar her boyut çalışır.
`no_face`	Bir yüz bulamadık Yüzünüzü kapatmadan, eşit ışıkta kameraya bakın.
`multiple_faces`	Fotoğrafta birden fazla kişi var Karede yalnızca siz olmalısınız.
`head_turned`	Başınız yana dönük Doğrudan kameraya bakın.
`head_tilted`	Başınız eğik Başınızı düz tutun ve dümdüz ileri bakın.
`eyes_closed`	Gözleriniz kapalı görünüyor İki gözünüzü de açın ve kameraya bakın.
`mouth_open`	Ağzınız açık Ağzınızı nötr bir ifadeyle kapatın.
`not_neutral`	İfade nötr değil Yüzünüzü gevşetin; gülümsemeyin.
`blurry`	Fotoğraf bulanık Sabit durun ve yüzünüzün net olduğundan emin olun.
`too_dark`	Fotoğraf çok karanlık Bir pencereye dönün veya önünüze ışık ekleyin.
`too_bright`	Fotoğraf aşırı pozlanmış Doğrudan ışıktan uzaklaşın.
`uneven_lighting`	Yüzün bir tarafında gölge var Işık yandan değil önünüzden gelmeli.
`not_color`	Bu belge renkli fotoğraf gerektiriyor Fotoğrafı renkli modda çekin.
`busy_background`	Arka plan karışık Arkanızdaki düz bir duvar daha temiz kenarlar verir — ya da uzman incelemesi ekleyin.
`head_not_measurable`	Başınızı ölçemedik İyi ışıkta kameraya bakın ve tekrar deneyin.
`low_resolution`	Yüz fotoğrafta çok küçük Daha yaklaşın veya daha büyük bir görüntü kullanın.
`crown_cut`	Başın üst kısmı kesilmiş Saçın üstünde boşluk bırakın.
`shoulders_cut`	Kare çeneye çok yakın bitiyor Omuzlarınızı da dahil edin.
`subject_cut_side`	Kişi kenardan kesilmiş Kendinizi ortalayın, iki yanda da eşit boşluk bırakın.
`eye_line_out_of_range`	Göz hizası izin verilen aralığın dışında Fotoğraf bunun yerine baş yüksekliğine göre kadrajlandı.
`head_size_out_of_range`	Baş boyutu bu belge için izin verilen aralığın dışında Baş kılavuza uyana kadar yakınlaştırın veya uzaklaştırın.
`file_size_over_limit`	Dosya bu belgenin izin verdiğinden büyük Kaliteyi kabul edilebilir en düşük düzeye indirdik.
`retouch_skipped`	Güvenle rötuşlanacak bir şey yoktu Orijinal görüntü korundu.

Hata kodları

Başarısız bir istek, HTTP durumuyla ve kodu bunlardan biri olan bir hata zarfıyla yanıt verir.

Kod	HTTP durumu	Anlamı
`background_not_allowed`	400	Bu arka plan rengi bu belge için izinli değil.
`credit_packs_disabled`	400	Kredi paketleri şu anda satışta değil.
`crop_out_of_bounds`	400	İstenen kırpma fotoğrafın dışına taşıyor.
`email_required`	400	Teslimat için bir e-posta adresi gerekiyor.
`invite_invalid`	400	Bu davet geçerli değil.
`magic_link_invalid`	400	Bu giriş bağlantısı geçersiz veya süresi dolmuş — yeni bir bağlantı isteyin.
`plan_not_available`	400	Bu plan mevcut değil.
`product_not_available`	400	Bu ürün şu anda mevcut değil.
`setting_out_of_range`	400	Ayar değeri izin verilen aralığın dışında.
`setting_unknown`	400	Bu ayar anahtarı tanınmıyor.
`totp_invalid`	400	Doğrulama kodu geçerli değil.
`turnstile_failed`	400	Bot karşıtı kontrol başarısız oldu — sayfayı yenileyip tekrar deneyin.
`webhook_invalid`	400	Webhook imzası veya içeriği geçersiz.
`api_key_invalid`	401	Bu API anahtarı geçerli değil.
`api_key_revoked`	401	Bu API anahtarı iptal edildi.
`session_expired`	401	Oturumunuzun süresi doldu — lütfen tekrar giriş yapın.
`unauthorized`	401	Devam etmek için giriş yapmanız gerekiyor.
`payment_required`	402	Bu siparişin ödemesi henüz yapılmadı.
`quota_exceeded`	402	Kuruluşun fotoğraf kotası doldu — planı yükseltin veya kredi paketi alın.
`review_quota_exceeded`	402	Bu fatura döneminde uzman incelemesi hakkı kalmadı.
`seat_limit`	402	Planınızda boş koltuk kalmadı — planı yükseltin veya bir üyeyi çıkarın.
`subscription_required`	402	Bunun için etkin bir abonelik gerekiyor — faturalandırmadan bir plan seçin.
`api_disabled`	403	Bu kuruluş için API açık değil.
`forbidden`	403	Buna erişiminiz yok.
`org_forbidden`	403	Bu kuruluştaki rolünüz buna izin vermiyor.
`org_suspended`	403	Bu kuruluş askıya alındı — destekle iletişime geçin.
`totp_required`	403	Bu işlem için ikinci bir doğrulama faktörü gerekiyor.
`client_not_found`	404	Bu müşteriyi bulamadık.
`handoff_not_found`	404	Bu bağlantının süresi doldu — yeni bir QR kodu gösterip tekrar tarayın.
`intake_disabled`	404	Bu alım bağlantısı etkin değil.
`not_found`	404	Bunu bulamadık.
`org_not_found`	404	Bu kuruluşu bulamadık.
`photo_not_found`	404	Bu fotoğrafı bulamadık.
`spec_not_found`	404	Bu belgeyi tanımıyoruz.
`upload_not_found`	404	Bu yükleme bulunamadı veya süresi doldu.
`already_paid`	409	Bu siparişin ödemesi zaten yapıldı.
`attempts_exhausted`	409	Yeniden deneme sınırına ulaştınız — bir inceleme uzmanı bu siparişe bakacak.
`invalid_state`	409	Bu işlem, siparişin şu anki durumunda mümkün değil.
`last_owner`	409	Bir kuruluşun en az bir sahibi kalmalı.
`org_slug_taken`	409	Bu bağlantı adı zaten alınmış.
`owner_of_organisation`	409	Bir kuruluşun tek sahibisiniz. Hesabınızı silmeden önce başka bir üyeyi sahip yapın veya kuruluşu silin.
`product_has_sales`	409	Satışı olan bir ürün silinemez — bunun yerine devre dışı bırakın.
`spec_switch_not_allowed`	409	Belge yalnızca bir kez, eşit veya daha düşük fiyatlı bir belgeyle değiştirilebilir.
`upload_already_used`	409	Bu yükleme zaten başka bir siparişe dönüştürüldü.
`invite_expired`	410	Bu davetin süresi doldu — sahibinden yenisini göndermesini isteyin.
`export_too_large`	413	Bu dışa aktarım 2 GB'ı aşıyor — daha kısa bir tarih aralığı seçin.
`image_url_invalid`	422	Görsel adresi herkese açık bir http(s) bağlantısı olmalı.
`image_url_unreachable`	422	Görseli bu adresten alamadık.
`logo_invalid`	422	Logo en fazla 1 MB boyutunda PNG veya JPEG olmalı.
`org_slug_reserved`	422	Bu bağlantı adı kullanılamaz.
`validation_error`	422	İstek geçerli değil.
`webhook_url_invalid`	422	Webhook adresi herkese açık bir https bağlantısı olmalı.
`rate_limited`	429	Çok fazla istek — lütfen bir an bekleyin.
`test_key_daily_limit`	429	Test anahtarının günlük sınırına ulaşıldı — daha fazlası için canlı anahtar kullanın.
`internal_error`	500	Bizim tarafımızda bir sorun oluştu.
`maintenance`	503	TakPhoto kısa bir bakımda — lütfen birkaç dakika sonra tekrar deneyin.

Webhook'lar

Anahtarınıza bir webhook URL'si ya da tek bir fotoğrafa callback_url tanımlayın; fotoğraf sonuçlandığı anda size gönderelim — sürekli sorgulamaya gerek yok.

Olaylar

photo.completed: Fotoğraf tamamlandı ve dosyaları hazır.
photo.failed: Fotoğraf üretilemedi. Hiçbir ücret alınmadı.
review.approved: Uzman incelemeci fotoğrafı onayladı.
review.rejected: Uzman incelemeci fotoğrafı reddetti; neden review.reason alanında.

Başlıklar

X-Event: Olayın adı.
X-Delivery-Id: Bu gönderimin kimliği.
X-Signature: İmza; anahtarınızın bir webhook sırrı olduğunda.

Yeniden denemeler

10 saniye içinde herhangi bir 2xx durumuyla yanıt verin. Başka her şey — farklı bir durum, bir yönlendirme ya da zamanında gelmeyen yanıt — başarısız bir denemedir ve gönderim yeniden denenir:

Deneme 1: hemen
Deneme 2: bir öncekinden 1 dakika sonra
Deneme 3: bir öncekinden 5 dakika sonra
Deneme 4: bir öncekinden 30 dakika sonra
Deneme 5: bir öncekinden 2 saat sonra

5. deneme de başarısız olursa gönderimden vazgeçilir.

Yük

JSON gövdeli bir POST: olay, ne zaman olduğu ve fotoğrafın API üzerinden okunduğunda döndüğü hâli. Aynı olay birden fazla kez gelebilir; bu yüzden tekrarları id alanına göre ayıklayın.

{
  "id": "evt_00000000000000000000000000000000",
  "event": "photo.completed",
  "created_at": "2026-01-01T12:00:00Z",
  "data": {
    "checks": [
      {
        "code": "string",
        "hint": "string",
        "result": "string",
        "value": 0
      }
    ],
    "created_at": "2026-01-01T12:00:00Z",
    "credits_charged": 0,
    "crop": {
      "rotation_deg": 0,
      "scale": 0,
      "x0": 0,
      "x1": 0,
      "y0": 0,
      "y1": 0
    },
    "expires_at": "2026-01-01T12:00:00Z",
    "id": "string",
    "outputs": {
      "digital": {
        "bytes": 0,
        "height": 0,
        "url": "string",
        "width": 0
      },
      "sheets": {
        "key": {
          "jpeg": "string",
          "pdf": "string"
        }
      }
    },
    "review": {
      "reason": "string",
      "status": "string"
    },
    "spec": {
      "id": "string",
      "version": 0
    },
    "status": "processing"
  }
}

İmzayı doğrulayın

X-Signature şu biçimdedir: t=<timestamp>,v1=<hex>. Webhook sırrınızla zaman damgası, bir nokta ve ham istek gövdesi üzerinden HMAC-SHA256 hesaplayın, sabit zamanlı bir karşılaştırmayla v1 ile kıyaslayın; farklıysa ya da zaman damgası saatinizden 300 saniyeden fazla uzaksa gönderimi reddedin.

import hashlib
import hmac
import time

TOLERANCE_S = 300


def verify(secret: str, header: str, raw_body: bytes) -> bool:
    """header is X-Signature; raw_body is the request body before any JSON parsing."""
    parts = dict(item.split("=", 1) for item in header.split(",") if "=" in item)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1 or abs(time.time() - int(t)) > TOLERANCE_S:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_S = 300;

/** header is X-Signature; rawBody is the request body as a Buffer, before any JSON parsing. */
export function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map((item) => item.split("=")));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1 || Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex"));
  const given = Buffer.from(parts.v1);
  return expected.length === given.length && timingSafeEqual(expected, given);
}

<?php
const TOLERANCE_S = 300;

// $header is X-Signature; $rawBody is file_get_contents('php://input'), before json_decode.
function verify(string $secret, string $header, string $rawBody): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (!ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > TOLERANCE_S) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $v1);
}

Fiyatlar

Canlı anahtarlar için aylık planlar. Test anahtarları her zaman ücretsizdir.

Değişiklik günlüğü

/api/v1 üzerindeki her değişiklik. Geriye dönük uyumsuz bir değişiklik yalnızca yeni bir sürümle gelir ve eski sürüm 12 ay çalışmaya devam eder.

v1 — 2026-09

/api/v1'in ilk sürümü.

Uç noktalar (Endpoints)

GET /specs ve GET /specs/{spec_id} — belge şartnamesi kataloğu.
POST /photos — bir fotoğraf yükleme (multipart veya korumalı bir image_url); 15 saniye içinde senkron bir yanıt, ya da sonucu sorgulamak için bir Location ile 202.
GET /photos/{photo_id} — bir fotoğrafın durumu ve çıktıları.
POST /photos/{photo_id}/adjust — bitmiş bir sonuç üzerinde ücretsiz kırpma/yakınlaştırma ayarı.
DELETE /photos/{photo_id} — fotoğrafın ve dosyalarının anında silinmesi.
GET /usage — kalan kota ve mevcut tüketim.
GET /content/legal/{name} ve GET /content/changelog/{name} — yasal belgeler ve bu değişiklik günlüğü, Markdown olarak.

Kimlik doğrulama

Kimlik doğrulamalı her çağrı Authorization: Bearer <anahtarınız> gerektirir. pk_live_... anahtarları kotanızdan sayılır ve gerçek dosyalar üretir; pk_test_... anahtarları tamamen ücretsizdir ve entegrasyonunuzu canlıya almadan önce test etmeniz için filigranlı bir önizleme üretir.

Webhook'lar

Anahtarınıza bir webhook_url (veya tek bir fotoğraf için bir callback_url) ayarlarsanız, X-Signature başlığında HMAC-SHA256 ile imzalanmış photo.completed, photo.failed, review.approved ve review.rejected olaylarını, teslimat başarısız olduğunda 5 kereye kadar otomatik yeniden denemeyle alırsınız.

Limitler

Kimlik doğrulamalı her yanıt X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset ve X-Quota-Remaining taşır. Aylık plan kotanızı aşmak, plan ayarınıza bağlı olarak ya hizmeti durdurur ya da aşımı faturalandırır.

Tüm entegrasyonu ücretsiz kurun

Test anahtarları ücretsizdir ve filigranlı bir önizleme döndürür; böylece ilk ücretli fotoğraftan önce her şey çalışır.

Test anahtarı alın

Tek API çağrısıyla kurallara uygun vesikalık fotoğraflar

Hızlı başlangıç

Test anahtarı alın

Fotoğraf gönderin

Sonucu okuyun

Kod örnekleri

API referansı

/photos

İstek gövdesi application/json

İstek gövdesi multipart/form-data

Yanıtlar

/photos/{photo_id}

Parametreler

Yanıtlar

Parametreler

Yanıtlar

/photos/{photo_id}/adjust

Parametreler

İstek gövdesi application/json

Yanıtlar

/specs

Parametreler

Yanıtlar

/specs/{spec_id}

Parametreler

Yanıtlar

/usage

Yanıtlar

Kontrol ve hata kodları

Kontrol kodları

Hata kodları

Webhook'lar

Olaylar

Başlıklar

Yeniden denemeler

Yük

İmzayı doğrulayın

Fiyatlar

Değişiklik günlüğü

v1 — 2026-09

Uç noktalar (Endpoints)

Kimlik doğrulama

Webhook'lar

Limitler

Tüm entegrasyonu ücretsiz kurun

`/photos`

İstek gövdesi `application/json`

İstek gövdesi `multipart/form-data`

`/photos/{photo_id}`

`/photos/{photo_id}/adjust`

İstek gövdesi `application/json`

`/specs`

`/specs/{spec_id}`

`/usage`