Saltearse al contenido

Integre los flujos de trabajo documentales en su aplicación

Desde la carga de un archivo hasta su traducción, la verificación del progreso y la descarga del resultado. Cada paso se explica en el orden en que se integra, con puntos de entrada para la gestión de archivos, el procesamiento de documentos y los servicios de audio y video.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Autenticación mediante clave API · las traducciones de archivos se ejecutan como trabajos asíncronos

Este sitio describe la API en la nube HTTP.

01 Comience con una solicitud que no cuesta créditos

Sección titulada «01 Comience con una solicitud que no cuesta créditos»

Confirme que su clave y su red funcionan antes de cargar los archivos. La verificación del saldo no consume créditos ni genera ningún trabajo de traducción.

  1. Obtener una clave API

    Inicie sesión en la Consola de API y cree una clave que comience con sk_. Utilice una clave independiente para cada aplicación y asóciela a un presupuesto.

    Una clave funciona para la cuenta que la creó. Guárdela en el servidor y léala desde una variable de entorno; nunca la incluya en el código fuente de una página web ni en un repositorio público.

  2. Verifique el saldo

    Establezca la variable de entorno OMNIDOC_API_KEY y luego ejecute cualquiera de los ejemplos a continuación. El éxito devuelve JSON; 401 indica que la clave presenta un problema y debe verificarse. Nunca muestre la clave completa en tickets, capturas de pantalla ni registros.

    Ventana de terminal
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Una carga exitosa solo indica que el archivo se ha almacenado. Después de crear un trabajo, espere a que alcance un estado final y, a continuación, liste y descargue sus resultados.

PasoMétodo y rutaQué conservar
Solicitar una cargaPOST /upload/presignupload_url, upload_headers, finalize_token
Envíe el archivoPUT al upload_url devueltoRespuesta de éxito; esta solicitud no incluye ninguna clave API
Confirme la cargaPOST /upload/finalizedocument.id
Cree una traducciónPOST /jobsTrabajo id
Consultar el estadoGET /jobs/{job_id}completed o failed
Enumere los resultadosGET /artifacts?job_id={job_id}Identificadores y formatos de artefactos
Descargar un resultadoGET /artifacts/{artifact_id}/downloadBytes del archivo y nombre del archivo de respuesta

Para la carga directa, envíe el upload_headers desde el servidor exactamente como se devuelve y nunca envíe X-API-Key a la dirección de almacenamiento. Si la dirección de carga caduca o la transferencia falla, solicite una nueva. Detalles: protocolo de carga , inicio rápido , flujo de trabajo completo de Node.js$ y campos de solicitud de traducción .

Cada entrada enumera las rutas, los campos de solicitud y los ejemplos. El estado del servicio de su cuenta y los límites de su clave se aplican a todos ellos.

04 Autenticación y propiedad de los recursos

Sección titulada «04 Autenticación y propiedad de los recursos»

Una clave API identifica una cuenta. No es una contraseña pública para descargar un archivo.

Encabezado de solicitud

Utilice X-API-Key: sk_… o Authorization: Bearer sk_…, uno de los dos por solicitud. Envíe Content-Type: application/json con cuerpos JSON.

Lo que puede alcanzar una llave

Una clave solo tiene acceso a los recursos que su cuenta puede utilizar; el estado del servicio, el presupuesto de la clave y la configuración de traducción permitida siguen siendo aplicables. Los cambios en la cuenta y la creación, rotación o revocación de claves se realizan en la consola.

Ver autenticación, presupuestos y rotación y servicios y permisos .

05 Incorporar el manejo de fallos de compilación en la integración

Sección titulada «05 Incorporar el manejo de fallos de compilación en la integración»

Un tiempo de espera agotado no significa que el trabajo no se haya creado. Distinga los errores reintentables de las solicitudes que requieren corrección, para evitar que algo se envíe o procese dos veces.

  • Creación idempotente : genere un Idempotency-Key para cada nueva operación de creación; cuando vuelva a intentar la misma operación, reutilice la clave original y el cuerpo de solicitud exactamente igual. Las operaciones de documentos, trabajos multimedia y creación de voz requieren la clave; para otros puntos finales de creación, consulte sus páginas de referencia.
  • Notificaciones asíncronas : la consulta periódica está bien para una primera integración; para un progreso continuo use SSE , y para recibir los estados finales en segundo plano utilice un webhook .
EstadoVerifique primeroQué hacer
401 / 403Clave, permisos, propiedad de los recursosCorrija las credenciales o los permisos; no vuelva a intentarlo sin verificar.
402Créditos disponiblesRecargue y vuelva a enviar
409Clave y cuerpo de idempotencia, estado del recursoConsulte la operación original antes de iniciar una nueva
422Errores de campo en la respuestaCorrija los parámetros o el archivo
429Negocio code y Retry-AfterLos límites de tasa y de cola pueden esperarse; primero debe aumentarse el presupuesto de claves agotado.
5xxError temporal del servicioRetraso exponencial limitado; conserve la clave de idempotencia para las solicitudes de creación

Conserve la cabecera de respuesta X-Request-Id, el tiempo de la solicitud y la ruta para la resolución de problemas; nunca registre la clave completa. Todos los códigos de error y ejemplos de reintento se encuentran en la referencia de errores . .

06 Verifique el funcionamiento de la facturación antes de integrarla

Sección titulada «06 Verifique el funcionamiento de la facturación antes de integrarla»

Sin créditos

La carga, la comprobación de trabajos, la descarga de resultados y la lectura del saldo y los registros de liquidación no consumen créditos; tampoco lo hacen los glosarios, proyectos, etiquetas, la búsqueda ni el uso compartido.

Facturado por uso

La traducción de archivos, las herramientas de documentos, la traducción instantánea y los servicios de audio y video se facturan según el uso real; la creación de un trabajo no constituye el cargo final.

Antes de que comience un trabajo, solo se verifica el umbral de saldo; una vez finalizado, se cobra el uso real. Si el saldo resulta insuficiente, la diferencia se registra como deuda y los créditos recibidos posteriormente se aplican primero para saldarla. Puede conciliar cargos y reembolsos por trabajo o por operación de crédito. Cuando se agota el presupuesto de una clave, aún puede consultar los trabajos, resultados y registros asociados a esa clave.