Exemples d’API

Version

API

Premiers pas avec l’API

Créer une clé API

Connectez-vous, créez une clé dans votre tableau de bord et vérifiez vos crédits disponibles.
Importer et envoyer

V2 : demandez les URL d’importation, importez les fichiers, puis envoyez la tâche de traduction.
Suivre la tâche

Utilisez le batch_id reçu pour suivre la progression jusqu’à la fin du traitement des images.
Télécharger les images traduites

Utilisez les URL des images traduites renvoyées pour les images traitées avec succès.

Entrées d’exemple

Clé API

Langue source

Langue cible

Modèle

Police

Python 3 · pip install requests

Route

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

Paramètres

Paramètre	Requis	Type	Description
`image`	Oui	file[]	Un ou plusieurs fichiers image, ou une archive ZIP
`source_language`	Non	string	Facultatif ; requis lorsque le modèle est manga (ex. ja)
`target_language`	Oui	string	Code de langue cible (ex. en)
`model`	Non	string	Modèle de reconnaissance ; omettez-le pour utiliser la valeur par défaut de l’API
`font`	Non	string	Style de police ; omettez-le pour utiliser la valeur par défaut de l’API

Paramètre	Requis	Type	Description
`Idempotency-Key`	Oui	HTTP header	En-tête de préparation : clé stable permettant de relancer en toute sécurité la même liste de fichiers pendant 8 heures
`files[]`	Oui	array<object>	Requête de préparation : métadonnées de fichier comprenant filename, content_type, size et content_sha256
`upload_id`	Oui	string	Requête finale : identifiant opaque du lot de téléversement renvoyé par la préparation
`files[].index files[].upload_intent`	Oui	integer string	Requête finale : index et upload_intent opaque de chaque fichier renvoyés par la préparation ; à envoyer uniquement après chaque téléversement vers R2
`source_language`	Non	string	Facultatif ; requis lorsque le modèle est manga (ex. ja)
`target_language`	Oui	string	Code de langue cible (ex. en)
`model`	Non	string	Modèle de reconnaissance ; omettez-le pour utiliser la valeur par défaut de l’API
`font`	Non	string	Style de police ; omettez-le pour utiliser la valeur par défaut de l’API

Paramètre	Requis	Type	Description
`batch_id`	Oui	string	Identifiant de lot utilisé pour consulter le statut de la tâche

Paramètre	Requis	Type	Description
Aucun paramètre

Paramètres de réponse

Champ	Type	Description
`task_id`	string	Identifiant de tâche
`batch_id`	string	Identifiant de lot utilisé pour consulter le statut de la tâche

Champ	Type	Description
`status`	integer	Code d’état de l’application ; 200 en cas de succès
`cost_ms`	integer	Temps de traitement de cette requête API en millisecondes
`request_id`	string	Identifiant de requête permettant de suivre cet appel API
`data`	object	Identifiants de la tâche de traduction renvoyés après acceptation de la requête
`message`	string	Toujours success pour une réponse API réussie ; cela ne signifie pas que la tâche de traduction est terminée
`data.task_id`	string	Identifiant de tâche
`data.batch_id`	string	Identifiant de lot utilisé pour consulter le statut de la tâche

Champ	Type	Description
`status_code`	integer	Toujours 200 pour une réponse Task Status réussie
`request_id`	string	Identifiant de requête permettant de suivre cet appel API
`auth_type`	string	Toujours account pour une requête Task Status authentifiée par PAT
`task_reference`	string	Le batch_id du chemin de la requête, renvoyé sans modification
`data`	object	Conteneur des résultats par image et de l’état global de la tâche
`data.items`	array<object>	Tableau des résultats de tâche par image
`data.items[].image_id`	string	Identifiant stable du résultat d’image
`data.items[].index`	integer	Position de l’image dans le lot, à partir de zéro
`data.items[].filename`	string	Nom du fichier image d’origine
`data.items[].status`	string	Statut du résultat d’image (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	URL de l’image source ; elle est disponible pour les tâches actuelles créées via l’API.
`data.items[].translated_url`	string	URL de l’image traduite ; chaîne vide tant qu’aucun résultat n’est disponible, notamment pour les images en attente, en cours ou en échec.
`data.items[].is_translated`	boolean	true uniquement lorsqu’une URL d’image traduite terminée est disponible
`data.items[].output_file_path`	string	Alias de compatibilité de translated_url ; chaîne vide lorsqu’aucune image traduite n’est disponible.
`data.items[].message`	string \| null	Message d’information facultatif
`data.items[].error`	string \| null	Détail de l’erreur en cas d’échec de la tâche image ; sinon null
`data.items[].inpaint_image_url`	string \| null	URL de l’image dont le texte a été effacé, ou null si le modèle ou le chemin d’exécution sélectionné ne la génère pas.
`data.items[].block_json`	array<object>	Blocs de texte structurés conservés par V1 ; peut être un tableau vide si le modèle ou le chemin ne renvoie pas de métadonnées de blocs.
`data.task_status`	string	Statut global de la tâche (pending \| processing \| completed \| failed \| canceled)

Champ	Type	Description
`status`	integer	Code d’état de l’application ; 200 en cas de succès
`cost_ms`	integer	Durée de la tâche en millisecondes ; 0 si les horodatages valides manquent
`request_id`	string	Identifiant de requête permettant de suivre cet appel API
`data`	array<object>	Tableau compact des résultats par image
`message`	string	Toujours success pour une réponse API réussie ; cela ne signifie pas que la tâche de traduction est terminée
`data[].image_id`	string	Identifiant stable du résultat d’image
`data[].filename`	string	Nom du fichier image d’origine
`data[].status`	string	Statut du résultat d’image (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	URL de l’image source ; elle est disponible pour les tâches actuelles créées via l’API.
`data[].translated_url`	string	URL de l’image traduite ; chaîne vide tant qu’aucun résultat n’est disponible, notamment pour les images en attente, en cours ou en échec.
`data[].erased_url`	string	URL de l’image dont le texte a été effacé ; peut être une chaîne vide. Les modèles ou chemins qui ne renvoient qu’une image finale, comme Manga avec le chemin d’image finale Auto, ne la génèrent pas.
`data[].blocks`	array<object>	Blocs de texte traduits structurés ; peut être un tableau vide si le modèle ou le chemin ne renvoie pas de métadonnées de blocs, comme Manga avec le chemin d’image finale Auto.
`data[].blocks[].angle`	number	Angle de rotation du bloc de texte
`data[].blocks[].color`	string	Couleur hexadécimale utilisée pour le texte traduit
`data[].blocks[].handwritten`	boolean	Indique si le texte source a été détecté comme manuscrit
`data[].blocks[].location`	object	Limites aux quatre coins du bloc de texte
`data[].blocks[].location.left_bottom`	array<number>	Paire de coordonnées du coin indiqué
`data[].blocks[].location.right_bottom`	array<number>	Paire de coordonnées du coin indiqué
`data[].blocks[].location.left_top`	array<number>	Paire de coordonnées du coin indiqué
`data[].blocks[].location.right_top`	array<number>	Paire de coordonnées du coin indiqué
`data[].blocks[].text`	string	Texte traduit rendu pour le bloc
`data[].blocks[].direction`	string	Direction d’écriture du texte traduit

Champ	Type	Description
`subscription_credits`	integer	Solde de crédits de la catégorie indiquée
`subscription_credits_expires_at`	string \| null	Date d’expiration des crédits d’abonnement au format ISO 8601, ou null
`one_time_credits`	integer	Solde de crédits de la catégorie indiquée
`one_time_credits_expires_at`	string \| null	Date d’expiration des crédits ponctuels au format ISO 8601, ou null
`free_credits`	integer	Solde de crédits de la catégorie indiquée
`total_credits`	integer	Somme de tous les soldes de crédits disponibles
`is_temporary`	boolean	Indique si le solde appartient à un compte temporaire

Champ	Type	Description
`status`	integer	Code d’état de l’application ; 200 en cas de succès
`cost_ms`	integer	Temps de traitement de cette requête API en millisecondes
`request_id`	string	Identifiant de requête permettant de suivre cet appel API
`data`	object	Conteneur des soldes de crédits actuels
`message`	string	Toujours success pour une réponse API réussie ; cela ne signifie pas que la tâche de traduction est terminée
`data.total_credits`	integer	Somme de tous les soldes de crédits disponibles
`data.is_temporary`	boolean	Indique si le solde appartient à un compte temporaire
`data.detail`	object	Répartition des crédits disponibles par catégorie
`data.detail.subscription`	object	Solde et expiration de la catégorie indiquée
`data.detail.subscription.credits`	integer	Solde de crédits de la catégorie indiquée
`data.detail.subscription.expires_at`	string \| null	Date d’expiration du crédit au format ISO 8601, ou null
`data.detail.one_time`	object	Solde et expiration de la catégorie indiquée
`data.detail.one_time.credits`	integer	Solde de crédits de la catégorie indiquée
`data.detail.one_time.expires_at`	string \| null	Date d’expiration du crédit au format ISO 8601, ou null
`data.detail.free`	object	Solde et expiration de la catégorie indiquée
`data.detail.free.credits`	integer	Solde de crédits de la catégorie indiquée
`data.detail.free.expires_at`	null	Toujours null, car cet endpoint agrégé ne fournit pas de date d’expiration unique pour les crédits gratuits

Réponse d’exemple (JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

Réponse d’exemple (JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

Réponse d’exemple (JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

Réponse d’exemple (JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

Réponse d’exemple (JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

Réponse d’exemple (JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

Paramètres de la réponse d’erreur

En cas d’échec de V2, le statut HTTP est conservé et la même enveloppe à cinq champs est renvoyée.

Champ	Type	Description
`status`	integer	Code d’état HTTP réel de l’erreur
`cost_ms`	integer	Temps de traitement de cette requête API en millisecondes
`request_id`	string	Identifiant de requête permettant de suivre cet appel API
`data`	object	Conteneur de données d’erreur contenant uniquement le code stable lisible par machine
`message`	string	Message d’erreur public ; les détails de diagnostic internes ne sont pas exposés
`data.code`	string	Code d’erreur stable lisible par machine

Exemple de réponse d’erreur (JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

Premiers pas avec l’API

Créer une clé API

Importer et envoyer

Suivre la tâche

Télécharger les images traduites

Entrées d’exemple

Route

Paramètres

Paramètres de réponse

Réponse d’exemple (JSON)

Réponse d’exemple (JSON)

Réponse d’exemple (JSON)

Réponse d’exemple (JSON)

Réponse d’exemple (JSON)

Réponse d’exemple (JSON)

Paramètres de la réponse d’erreur

Exemple de réponse d’erreur (JSON)

Préférences de cookies