API bêta pour un seul visage

L’API bêta Kirkify accepte une image contenant un seul visage bien visible et renvoie une tâche de génération asynchrone. Elle est conçue pour les intégrations de serveur à serveur. N’exposez jamais une clé API dans le JavaScript du navigateur, une application mobile ou un dépôt public.

Acheter l’accès

Achetez le forfait API bêta à paiement unique sur la page Clés API :

$59.99, payés via Stripe
1 000 crédits de génération
Les crédits n’expirent jamais après le paiement
Chaque requête acceptée réserve un crédit
Les générations échouées sont automatiquement remboursées

Après confirmation du paiement par Stripe, créez jusqu’à deux clés API actives sur la même page. Une clé n’est affichée qu’une seule fois. Si vous la perdez, révoquez-la et créez-en une nouvelle.

Créer une tâche

Envoyez une image JPG, PNG ou WEBP en multipart/form-data. Le champ image est obligatoire et ne doit pas dépasser 8 Mo.

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

L’API renvoie le statut 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"
}

Consulter l’état de la tâche

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

Une tâche terminée renvoie :

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

Interrogez l’état toutes les 2 à 5 secondes jusqu’à obtenir succeeded, failed ou canceled. Les fichiers sont temporaires. Téléchargez immédiatement un résultat réussi ; les médias d’entrée et de sortie peuvent être supprimés après 24 heures.

Réessayer sans risque de doublon

Chaque requête POST nécessite un en-tête Idempotency-Key contenant un UUID. Conservez la clé associée à l’image dans votre propre base de données pendant au moins 24 heures.

En cas d’expiration du délai réseau, réessayez avec la même clé et des octets d’image identiques.
Une requête correspondante déjà terminée renvoie la réponse d’origine sans facturation supplémentaire.
La même clé utilisée avec une image différente renvoie HTTP 409 idempotency_conflict.
Deux requêtes simultanées utilisant la même clé peuvent renvoyer 409 idempotency_request_in_progress. Réessayez après le délai indiqué par Retry-After.
Dès qu’une tâche est acceptée, la même clé renvoie toujours sa réponse 202 d’origine. Interrogez la tâche jusqu’à son état final. En cas d’échec, le crédit est remboursé ; utilisez une nouvelle clé d’idempotence pour lancer une autre tâche.
Après 24 heures, la clé peut être réutilisée pour une nouvelle requête.

Limites

Les limites s’appliquent au compte, et non à chaque clé API :

30 requêtes par minute glissante
10 tâches de génération simultanées
2 clés API actives

Les réponses HTTP 429 incluent un en-tête Retry-After exprimé en secondes. Attendez ce délai avant de réessayer.

Erreurs

Chaque erreur comporte un code stable et un identifiant de requête pour l’assistance :

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

HTTP	Code	Signification
400	`image_required`, `invalid_form_data`, `invalid_idempotency_key`	Une donnée obligatoire est absente ou mal formée
401	`invalid_api_key`	La clé ou le compte est inactif
402	`insufficient_credits`	Achetez un autre forfait avant de créer une nouvelle tâche
404	`task_not_found`	La tâche n’existe pas ou appartient à un autre compte
409	`idempotency_conflict`, `idempotency_request_in_progress`	La clé a été mal réutilisée ou est encore en cours de traitement
413	`image_too_large`	L’image dépasse 8 Mo
415	`unsupported_media_type`	Les données ne correspondent pas à une image JPG, PNG ou WEBP
422	`invalid_image`	L’image ne peut pas être décodée
429	`rate_limit_exceeded`, `concurrency_limit_exceeded`	Attendez le délai indiqué par `Retry-After`
503	`api_temporarily_disabled`, `service_unavailable`, `admission_unavailable`	Aucune tâche n’a été acceptée ; réessayez plus tard avec la même clé

La détection des visages est asynchrone. Une tâche sans visage exploitable renvoie status: failed, le code no_face_detected et credits_refunded: true. Une image contenant plusieurs visages rejetée par le fournisseur renvoie multiple_faces_detected avec le même remboursement. Les autres codes d’échec asynchrones sont input_upload_failed, provider_creation_failed, provider_failed, provider_output_missing, provider_canceled, generation_failed, generation_canceled et result_unavailable. Les GIF, vidéos, requêtes par lots, SDK et webhooks clients ne sont pas disponibles dans la première version.