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.
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.
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.
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.
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.
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"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());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.
| Paso | Método y ruta | Qué conservar |
|---|---|---|
| Solicitar una carga | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Envíe el archivo | PUT al upload_url devuelto | Respuesta de éxito; esta solicitud no incluye ninguna clave API |
| Confirme la carga | POST /upload/finalize | document.id |
| Cree una traducción | POST /jobs | Trabajo id |
| Consultar el estado | GET /jobs/{job_id} | completed o failed |
| Enumere los resultados | GET /artifacts?job_id={job_id} | Identificadores y formatos de artefactos |
| Descargar un resultado | GET /artifacts/{artifact_id}/download | Bytes 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.
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 .
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.
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.| Estado | Verifique primero | Qué hacer |
|---|---|---|
401 / 403 | Clave, permisos, propiedad de los recursos | Corrija las credenciales o los permisos; no vuelva a intentarlo sin verificar. |
402 | Créditos disponibles | Recargue y vuelva a enviar |
409 | Clave y cuerpo de idempotencia, estado del recurso | Consulte la operación original antes de iniciar una nueva |
422 | Errores de campo en la respuesta | Corrija los parámetros o el archivo |
429 | Negocio code y Retry-After | Los límites de tasa y de cola pueden esperarse; primero debe aumentarse el presupuesto de claves agotado. |
5xx | Error temporal del servicio | Retraso 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 . .
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.