Single-Face API Beta

The Kirkify API Beta accepts one image containing one clear face and returns an asynchronous generation task. It is designed for server-to-server integrations. Never expose an API key in browser JavaScript, a mobile app, or a public repository.

Purchase access

Purchase the one-time API Beta package at API Keys:

• $59.99 paid through Stripe
• 1,000 generation credits
• Credits never expire after payment
• One accepted request reserves one credit
• Failed generations are refunded automatically

After Stripe confirms the payment, create up to two active API keys on the same page. A key is displayed only once. If it is lost, revoke it and create a replacement.

Create a task

Send JPG, PNG, or WEBP image bytes as multipart/form-data. The image field is required and may not exceed 8MB.

curl --request POST https://kirkifyai.net/api/v1/kirkify \
  --header "Authorization: Bearer kirk_live_YOUR_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --form "[email protected]"

The API returns HTTP 202 Accepted:

{
  "task_id": "task_V1StGXR8_Z5jdHi6B-myT",
  "status": "processing",
  "credits_used": 1,
  "status_url": "https://kirkifyai.net/api/v1/kirkify/task_V1StGXR8_Z5jdHi6B-myT"
}

Poll the task

curl --request GET https://kirkifyai.net/api/v1/kirkify/task_V1StGXR8_Z5jdHi6B-myT \
  --header "Authorization: Bearer kirk_live_YOUR_API_KEY"

A completed task returns:

{
  "task_id": "task_V1StGXR8_Z5jdHi6B-myT",
  "status": "succeeded",
  "result": {
    "image_url": "https://img.kirkifyai.net/kirkify/output/..."
  }
}

Poll every 2 to 5 seconds until the status is succeeded, failed, or canceled. Files are temporary. Download a successful result immediately; input and output media may be removed after 24 hours.

Safe retries

Every POST requires a UUID Idempotency-Key. Keep the key associated with the image in your own database for at least 24 hours.

• Retry a network timeout with the same key and identical image bytes.
• A completed matching request returns the original response without another charge.
• The same key with different image bytes returns HTTP 409 idempotency_conflict.
• Two simultaneous requests with the same key may return 409 idempotency_request_in_progress. Retry after the Retry-After delay.
• Once a task is accepted, the same key always replays its original 202 response. Poll the task to its terminal state. If it fails, the credit is refunded; use a new idempotency key to start another task.
• After 24 hours, the key may be used for a new request.

Limits

Limits apply to the account, not to each API key:

• 30 requests per rolling minute
• 10 concurrent generation tasks
• 2 active API keys

HTTP 429 responses include a Retry-After header in seconds. Wait for that duration before retrying.

Errors

Errors use a stable code and a support request ID:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "At most 30 new generation requests are allowed per rolling minute",
    "request_id": "req_..."
  }
}

Face detection occurs asynchronously. A task with no usable face returns status: failed, error code no_face_detected, and credits_refunded: true. A provider-rejected multiple-face image returns multiple_faces_detected with the same refund behavior. Other asynchronous failure codes include input_upload_failed, provider_creation_failed, provider_failed, provider_output_missing, provider_canceled, generation_failed, generation_canceled, and result_unavailable. GIF, video, batch requests, SDKs, and customer webhooks are not available in the first version.