La API Vision puede detectar y transcribir texto de archivos PDF y TIFF almacenados en Cloud Storage.
La detección de texto de documentos PDF y TIFF debe solicitarse mediante la función files:asyncBatchAnnotate
, que realiza una solicitud sin conexión (asíncrona) y proporciona su estado mediante los recursos operations
.
La salida de una solicitud de PDF o TIFF se escribe en un archivo JSON creado en el segmento de Cloud Storage especificado.
Limitaciones
La API Vision acepta archivos PDF o TIFF de hasta 2000 páginas. Los archivos más grandes devolverán un error.
Autenticación
Las claves de API no se admiten en las solicitudes de files:asyncBatchAnnotate
. Consulta Usar una cuenta de servicio para obtener instrucciones sobre cómo autenticarte con una cuenta de servicio.
La cuenta que se utilice para la autenticación debe tener acceso al segmento de Cloud Storage que especifiques para la salida (roles/editor
o roles/storage.objectCreator
o versiones posteriores).
Puedes usar una clave de API para consultar el estado de la operación. Consulta las instrucciones en Usar una clave de API.
Solicitudes de detección de texto en documentos
Actualmente, la detección de documentos PDF o TIFF solo está disponible para los archivos almacenados en segmentos de Cloud Storage. Los archivos JSON de respuesta se guardan de forma similar en un segmento de Cloud Storage.

gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
,
Fuente:
Oficina del Censo de los Estados Unidos.
REST
Antes de usar los datos de la solicitud, haz las siguientes sustituciones:
- CLOUD_STORAGE_BUCKET: un segmento o directorio de Cloud Storage en el que guardar los archivos de salida. Se expresa de la siguiente forma:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI: la ruta a un archivo válido (PDF o TIFF) en un segmento de Cloud Storage. Debe tener al menos privilegios de lectura en el archivo.
Ejemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE: un tipo de función válido.
Para las solicitudes
files:asyncBatchAnnotate
, puede usar los siguientes tipos de funciones:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID: tu ID de proyecto Google Cloud .
Consideraciones específicas de los campos:
inputConfig
: sustituye al campoimage
que se usa en otras solicitudes de la API Vision. Contiene dos campos secundarios:gcsSource.uri
: el URI de Google Cloud Storage del archivo PDF o TIFF (accesible para el usuario o la cuenta de servicio que hace la solicitud).mimeType
: uno de los tipos de archivo aceptados:application/pdf
oimage/tiff
.
outputConfig
: especifica los detalles de la salida. Contiene dos campos secundarios:gcsDestination.uri
: un URI de Google Cloud Storage válido. El usuario o la cuenta de servicio que hace la solicitud debe tener permiso de escritura en el segmento. El nombre del archivo seráoutput-x-to-y
, dondex
yy
representan los números de página del PDF o TIFF incluidos en ese archivo de salida. Si el archivo existe, su contenido se sobrescribirá.batchSize
: especifica cuántas páginas de salida se deben incluir en cada archivo JSON de salida.
Método HTTP y URL:
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
Cuerpo JSON de la solicitud:
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_FILE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/files:asyncBatchAnnotate"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content
Una solicitud asyncBatchAnnotate
correcta devuelve una respuesta con un solo campo de nombre:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Este nombre representa una operación de larga duración con un ID asociado (por ejemplo, 1efec2285bd442df
), que se puede consultar mediante la API v1.operations
.
Para recuperar la respuesta de anotación de Vision, envía una solicitud GET al endpoint v1.operations
y pasa el ID de operación en la URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Por ejemplo:
curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df
Si la operación está en curso:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "RUNNING", "createTime": "2019-05-15T21:10:08.401917049Z", "updateTime": "2019-05-15T21:10:33.700763554Z" } }
Una vez que se haya completado la operación, el state
se mostrará como DONE
y los resultados se escribirán en el archivo de Google Cloud Storage que hayas especificado:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "DONE", "createTime": "2019-05-15T20:56:30.622473785Z", "updateTime": "2019-05-15T20:56:41.666379749Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse", "responses": [ { "outputConfig": { "gcsDestination": { "uri": "gs://your-bucket-name/folder/" }, "batchSize": 1 } } ] } }
El JSON de tu archivo de salida es similar al de una [solicitud de detección de texto de documento](/vision/docs/ocr) de una imagen, con la adición de un campo context
que muestra la ubicación del PDF o TIFF especificado y el número de páginas del archivo:
output-1-to-1.json
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración de Go que se indican en la guía de inicio rápido de Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de Vision.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración de Java que se indican en la guía de inicio rápido de la API Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Vision en Java.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración de Node.js que se indican en la guía de inicio rápido de Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de Vision.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración de Python que se indican en la guía de inicio rápido de Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de Vision.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
gcloud
El comando gcloud
que uses dependerá del tipo de archivo.
Para realizar la detección de texto en PDF, usa el comando
gcloud ml vision detect-text-pdf
, como se muestra en el siguiente ejemplo:gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Para realizar la detección de texto TIFF, usa el comando
gcloud ml vision detect-text-tiff
como se muestra en el siguiente ejemplo:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
Idiomas adicionales
C#: Sigue las instrucciones de configuración de C# en la página de bibliotecas de cliente y, a continuación, consulta la documentación de referencia de Vision para .NET.
PHP Sigue las instrucciones de configuración de PHP en la página de bibliotecas de cliente y, a continuación, consulta la documentación de referencia de Vision para PHP.
Ruby: Sigue las instrucciones de configuración de Ruby en la página de bibliotecas de cliente y, a continuación, consulta la documentación de referencia de Vision para Ruby.
Asistencia multirregional
Ahora puedes especificar el almacenamiento de datos y el procesamiento OCR a nivel continental. Actualmente se admiten las siguientes regiones:
us
: solo en EE. UU.eu
: la Unión Europea
Ubicaciones
Cloud Vision te ofrece cierto control sobre dónde se almacenan y procesan los recursos de tu proyecto. En concreto, puede configurar Cloud Vision para que almacene y trate sus datos únicamente en la Unión Europea.
De forma predeterminada, Cloud Vision almacena y procesa los recursos en una ubicación global, lo que significa que Cloud Vision no garantiza que tus recursos permanezcan en una ubicación o región concretas. Si eliges la ubicación Unión Europea, Google almacenará tus datos y los tratará únicamente en la Unión Europea. Tanto tú como tus usuarios podéis acceder a los datos desde cualquier ubicación.
Definir la ubicación mediante la API
La API Vision admite un punto de conexión de API global (vision.googleapis.com
) y dos puntos de conexión basados en regiones: uno para la Unión Europea (eu-vision.googleapis.com
) y otro para Estados Unidos (us-vision.googleapis.com
). Usa estos puntos de conexión para el procesamiento específico de cada región. Por ejemplo, para almacenar y tratar tus datos solo en la Unión Europea, usa el URI eu-vision.googleapis.com
en lugar de vision.googleapis.com
en tus llamadas a la API REST:
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:annotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:asyncBatchAnnotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:annotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:asyncBatchAnnotate
Para almacenar y tratar tus datos solo en Estados Unidos, usa el endpoint de EE. UU. (us-vision.googleapis.com
) con los métodos anteriores.
Definir la ubicación mediante las bibliotecas de cliente
Las bibliotecas de cliente de la API Vision acceden al endpoint de la API global (vision.googleapis.com
) de forma predeterminada. Para almacenar y tratar sus datos únicamente en la Unión Europea, debe definir explícitamente el endpoint (eu-vision.googleapis.com
). En los siguientes ejemplos de código se muestra cómo configurar este ajuste.
REST
Antes de usar los datos de la solicitud, haz las siguientes sustituciones:
- REGION_ID: uno de los identificadores de ubicación regional válidos:
us
: solo en EE. UU.eu
: la Unión Europea
- CLOUD_STORAGE_IMAGE_URI: la ruta a un archivo de imagen válido en un segmento de Cloud Storage. Debe tener al menos privilegios de lectura en el archivo.
Ejemplo:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET: un segmento o directorio de Cloud Storage en el que guardar los archivos de salida. Se expresa de la siguiente forma:
gs://bucket/directory/
- FEATURE_TYPE: un tipo de función válido.
Para las solicitudes
files:asyncBatchAnnotate
, puede usar los siguientes tipos de funciones:DOCUMENT_TEXT_DETECTION
TEXT_DETECTION
- PROJECT_ID: tu ID de proyecto Google Cloud .
Consideraciones específicas de los campos:
inputConfig
: sustituye al campoimage
que se usa en otras solicitudes de la API Vision. Contiene dos campos secundarios:gcsSource.uri
: el URI de Google Cloud Storage del archivo PDF o TIFF (accesible para el usuario o la cuenta de servicio que hace la solicitud).mimeType
: uno de los tipos de archivo aceptados:application/pdf
oimage/tiff
.
outputConfig
: especifica los detalles de la salida. Contiene dos campos secundarios:gcsDestination.uri
: un URI de Google Cloud Storage válido. El usuario o la cuenta de servicio que hace la solicitud debe tener permiso de escritura en el segmento. El nombre del archivo seráoutput-x-to-y
, dondex
yy
representan los números de página del PDF o TIFF incluidos en ese archivo de salida. Si el archivo existe, su contenido se sobrescribirá.batchSize
: especifica cuántas páginas de salida se deben incluir en cada archivo JSON de salida.
Método HTTP y URL:
POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate
Cuerpo JSON de la solicitud:
{ "requests":[ { "inputConfig": { "gcsSource": { "uri": "CLOUD_STORAGE_IMAGE_URI" }, "mimeType": "application/pdf" }, "features": [ { "type": "FEATURE_TYPE" } ], "outputConfig": { "gcsDestination": { "uri": "CLOUD_STORAGE_BUCKET" }, "batchSize": 1 } } ] }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate" | Select-Object -Expand Content
Una solicitud asyncBatchAnnotate
correcta devuelve una respuesta con un solo campo de nombre:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
Este nombre representa una operación de larga duración con un ID asociado (por ejemplo, 1efec2285bd442df
), que se puede consultar mediante la API v1.operations
.
Para recuperar la respuesta de anotación de Vision, envía una solicitud GET al endpoint v1.operations
y pasa el ID de operación en la URL:
GET https://vision.googleapis.com/v1/operations/operation-id
Por ejemplo:
curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df
Si la operación está en curso:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "RUNNING", "createTime": "2019-05-15T21:10:08.401917049Z", "updateTime": "2019-05-15T21:10:33.700763554Z" } }
Una vez que se haya completado la operación, el state
se mostrará como DONE
y los resultados se escribirán en el archivo de Google Cloud Storage que hayas especificado:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "DONE", "createTime": "2019-05-15T20:56:30.622473785Z", "updateTime": "2019-05-15T20:56:41.666379749Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse", "responses": [ { "outputConfig": { "gcsDestination": { "uri": "gs://your-bucket-name/folder/" }, "batchSize": 1 } } ] } }
El JSON de tu archivo de salida es similar al de la respuesta de detección de texto de un documento
de una imagen si has usado la función DOCUMENT_TEXT_DETECTION
, o al de la respuesta de detección de texto
si has usado la función TEXT_DETECTION
. El resultado tendrá un campo context
adicional que mostrará la ubicación del PDF o TIFF especificado y el número de páginas del archivo:
output-1-to-1.json
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración de Go que se indican en la guía de inicio rápido de Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de Vision.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración de Java que se indican en la guía de inicio rápido de la API Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Vision en Java.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración de Node.js que se indican en la guía de inicio rápido de Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de Vision.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración de Python que se indican en la guía de inicio rápido de Vision con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de Vision.
Para autenticarte en Vision, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.
Pruébalo
Si es la primera vez que utilizas Google Cloud, crea una cuenta para evaluar el rendimiento de Cloud Vision API en situaciones reales. Los nuevos clientes también reciben 300 USD en crédito gratuito para ejecutar, probar y desplegar cargas de trabajo.
Prueba la API Cloud Vision gratis