Ejemplos de API

Versión

API

Ruta

POST PUT POST

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

Parámetros

Parámetro	Obligatorio	Tipo	Descripción
`image`	Sí	file[]	Uno o varios archivos de imagen, o un archivo ZIP
`source_language`	No	string	Opcional; obligatorio cuando el modelo es manga (p. ej., ja)
`target_language`	Sí	string	Código del idioma de destino (p. ej., en)
`model`	No	string	Modelo de reconocimiento; omítelo para usar el valor predeterminado de la API
`font`	No	string	Estilo de fuente; omítelo para usar el valor predeterminado de la API

Parámetro	Obligatorio	Tipo	Descripción
`Idempotency-Key`	Sí	HTTP header	Encabezado de preparación: clave estable para reintentar de forma segura la misma lista de archivos durante 8 horas
`platform`	No	string \| null	Solicitudes de preparación y final: etiqueta de plataforma opcional declarada por el cliente, usada solo para auditar llamadas API
`files[]`	Sí	array<object>	Solicitud de preparación: metadatos de archivo con filename, content_type, size y content_sha256
`upload_id`	Sí	string	Solicitud final: identificador opaco del lote de carga devuelto por la preparación
`files[].index files[].upload_intent`	Sí	integer string	Solicitud final: index y upload_intent opaco de cada archivo devueltos por la preparación; envíalos solo tras completar cada carga a R2
`source_language`	No	string	Opcional; obligatorio cuando el modelo es manga (p. ej., ja)
`target_language`	Sí	string	Código del idioma de destino (p. ej., en)
`model`	No	string	Modelo de reconocimiento; omítelo para usar el valor predeterminado de la API
`font`	No	string	Estilo de fuente; omítelo para usar el valor predeterminado de la API

Parámetro	Obligatorio	Tipo	Descripción
`batch_id`	Sí	string	Identificador de lote para consultar el estado de la tarea

Parámetro	Obligatorio	Tipo	Descripción
Sin parámetros

Parámetros de respuesta

Campo	Tipo	Descripción
`task_id`	string	Identificador de tarea
`batch_id`	string	Identificador de lote para consultar el estado de la tarea

Campo	Tipo	Descripción
`status`	integer	Código de estado de la aplicación; 200 cuando la respuesta es correcta
`cost_ms`	integer	Tiempo de procesamiento de esta solicitud API en milisegundos
`request_id`	string	Identificador de solicitud para rastrear esta llamada API
`data`	object	Identificadores de la tarea de traducción devueltos al aceptar la solicitud
`message`	string	Siempre success en una respuesta correcta de la API; no significa que la tarea de traducción haya finalizado
`data.task_id`	string	Identificador de tarea
`data.batch_id`	string	Identificador de lote para consultar el estado de la tarea

Campo	Tipo	Descripción
`status_code`	integer	Siempre 200 en una respuesta correcta de Task Status
`request_id`	string	Identificador de solicitud para rastrear esta llamada API
`auth_type`	string	Siempre account en una solicitud de Task Status autenticada con PAT
`task_reference`	string	El batch_id de la ruta de la solicitud, devuelto sin cambios
`data`	object	Contenedor de resultados por imagen y del estado general de la tarea
`data.items`	array<object>	Lista de resultados de tarea por imagen
`data.items[].image_id`	string	Identificador estable del resultado de imagen
`data.items[].index`	integer	Posición de la imagen en el lote, empezando en cero
`data.items[].filename`	string	Nombre de archivo de la imagen original
`data.items[].status`	string	Estado del resultado de imagen (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	URL de la imagen de origen; está disponible para las tareas actuales creadas mediante la API.
`data.items[].translated_url`	string	URL de la imagen traducida; es una cadena vacía hasta que el resultado esté disponible, también para imágenes pendientes, en proceso o fallidas.
`data.items[].is_translated`	boolean	Solo es true cuando está disponible la URL de una imagen traducida completada
`data.items[].output_file_path`	string	Alias compatible de translated_url; es una cadena vacía cuando no hay imagen traducida disponible.
`data.items[].message`	string \| null	Mensaje informativo opcional
`data.items[].error`	string \| null	Detalle del error cuando falla la tarea de imagen; en caso contrario, null
`data.items[].inpaint_image_url`	string \| null	URL de la imagen con el texto borrado, o null cuando el modelo o la ruta de ejecución seleccionados no la generan.
`data.items[].block_json`	array<object>	Bloques de texto estructurados conservados por V1; puede ser una matriz vacía cuando el modelo o la ruta no devuelve metadatos de bloques.
`data.task_status`	string	Estado general de la tarea (pending \| processing \| completed \| failed \| canceled)

Campo	Tipo	Descripción
`status`	integer	Código de estado de la aplicación; 200 cuando la respuesta es correcta
`cost_ms`	integer	Tiempo transcurrido de la tarea en milisegundos; 0 si faltan marcas de tiempo válidas
`request_id`	string	Identificador de solicitud para rastrear esta llamada API
`data`	array<object>	Lista compacta de resultados por imagen
`message`	string	Siempre success en una respuesta correcta de la API; no significa que la tarea de traducción haya finalizado
`data[].image_id`	string	Identificador estable del resultado de imagen
`data[].filename`	string	Nombre de archivo de la imagen original
`data[].status`	string	Estado del resultado de imagen (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	URL de la imagen de origen; está disponible para las tareas actuales creadas mediante la API.
`data[].translated_url`	string	URL de la imagen traducida; es una cadena vacía hasta que el resultado esté disponible, también para imágenes pendientes, en proceso o fallidas.
`data[].erased_url`	string	URL de la imagen con el texto borrado; puede ser una cadena vacía. Los modelos o rutas que solo devuelven una imagen final, como Manga con la ruta de imagen final Auto, no la generan.
`data[].blocks`	array<object>	Bloques de texto traducido estructurados; puede ser una matriz vacía cuando el modelo o la ruta no devuelve metadatos de bloques, como Manga con la ruta de imagen final Auto.
`data[].blocks[].angle`	number	Ángulo de rotación del bloque de texto
`data[].blocks[].color`	string	Color hexadecimal usado para el texto traducido
`data[].blocks[].handwritten`	boolean	Indica si el texto original se detectó como manuscrito
`data[].blocks[].location`	object	Límites de las cuatro esquinas del bloque de texto
`data[].blocks[].location.left_bottom`	array<number>	Par de coordenadas de la esquina indicada
`data[].blocks[].location.right_bottom`	array<number>	Par de coordenadas de la esquina indicada
`data[].blocks[].location.left_top`	array<number>	Par de coordenadas de la esquina indicada
`data[].blocks[].location.right_top`	array<number>	Par de coordenadas de la esquina indicada
`data[].blocks[].text`	string	Texto traducido renderizado para el bloque
`data[].blocks[].direction`	string	Dirección de escritura del texto traducido

Campo	Tipo	Descripción
`subscription_credits`	integer	Saldo de créditos de la categoría indicada
`subscription_credits_expires_at`	string \| null	Fecha de vencimiento de los créditos de suscripción en formato ISO 8601, o null
`one_time_credits`	integer	Saldo de créditos de la categoría indicada
`one_time_credits_expires_at`	string \| null	Fecha de vencimiento de los créditos de un solo uso en formato ISO 8601, o null
`free_credits`	integer	Saldo de créditos de la categoría indicada
`total_credits`	integer	Suma de todos los saldos de créditos disponibles
`is_temporary`	boolean	Indica si el saldo pertenece a una cuenta temporal

Campo	Tipo	Descripción
`status`	integer	Código de estado de la aplicación; 200 cuando la respuesta es correcta
`cost_ms`	integer	Tiempo de procesamiento de esta solicitud API en milisegundos
`request_id`	string	Identificador de solicitud para rastrear esta llamada API
`data`	object	Contenedor de los saldos de créditos actuales
`message`	string	Siempre success en una respuesta correcta de la API; no significa que la tarea de traducción haya finalizado
`data.total_credits`	integer	Suma de todos los saldos de créditos disponibles
`data.is_temporary`	boolean	Indica si el saldo pertenece a una cuenta temporal
`data.detail`	object	Desglose de los créditos disponibles por categoría
`data.detail.subscription`	object	Saldo y vencimiento de la categoría indicada
`data.detail.subscription.credits`	integer	Saldo de créditos de la categoría indicada
`data.detail.subscription.expires_at`	string \| null	Fecha de vencimiento del crédito en formato ISO 8601, o null
`data.detail.one_time`	object	Saldo y vencimiento de la categoría indicada
`data.detail.one_time.credits`	integer	Saldo de créditos de la categoría indicada
`data.detail.one_time.expires_at`	string \| null	Fecha de vencimiento del crédito en formato ISO 8601, o null
`data.detail.free`	object	Saldo y vencimiento de la categoría indicada
`data.detail.free.credits`	integer	Saldo de créditos de la categoría indicada
`data.detail.free.expires_at`	null	Siempre null porque este endpoint agregado no proporciona una única fecha de vencimiento para los créditos gratuitos

Respuesta de ejemplo (JSON)

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

Respuesta de ejemplo (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"
}

Respuesta de ejemplo (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"
  }
}

Respuesta de ejemplo (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"
}

Respuesta de ejemplo (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
}

Respuesta de ejemplo (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"
}

Parámetros de la respuesta de error

Cuando se produce un error en V2, se conserva el estado HTTP y se devuelve la misma envoltura de cinco campos.

Campo	Tipo	Descripción
`status`	integer	Código de estado de error HTTP real
`cost_ms`	integer	Tiempo de procesamiento de esta solicitud API en milisegundos
`request_id`	string	Identificador de solicitud para rastrear esta llamada API
`data`	object	Contenedor de datos de error que solo contiene el código estable legible por máquina
`message`	string	Mensaje de error público; no se exponen los detalles internos de diagnóstico
`data.code`	string	Código de error estable legible por máquina

Ejemplo de respuesta de error (JSON)

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

Entradas de ejemplo

Clave API

Idioma de origen

Idioma de destino

Modelo

Fuente

Ejemplos de API

Ruta

Parámetros

Parámetros de respuesta

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Parámetros de la respuesta de error

Ejemplo de respuesta de error (JSON)

Entradas de ejemplo

Ejemplo en Python3

Ejemplos cURL

Ejemplo en Python3

cURL

Ejemplo en Python3

cURL

Ruta

Parámetros

Parámetros de respuesta

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Respuesta de ejemplo (JSON)

Parámetros de la respuesta de error

Ejemplo de respuesta de error (JSON)

Entradas de ejemplo

Ejemplo en Python3

Ejemplos cURL

Ejemplo en Python3

cURL

Ejemplo en Python3

cURL

Preferencias de Cookies