# General Translation Platform: Descripción general URL: https://generaltranslation.com/es/docs/platform/openapi/overview.mdx Docs index: https://generaltranslation.com/llms.txt Description: Llama a los endpoints públicos de la API de General Translation y descarga la especificación OpenAPI. Usa la API de General Translation para crear flujos de trabajo de automatización personalizados. La CLI gestiona la mayoría de las llamadas a la API por ti. Usa el [cliente de TypeScript `@generaltranslation/api`](/docs/platform/core/reference/api-client) para obtener tipos generados de solicitud y respuesta, o llama a los endpoints directamente cuando necesites una automatización personalizada. La especificación OpenAPI define estos endpoints en un formato legible por máquinas. ## Conceptos básicos de la API [#api-basics] ### URL base Todos los endpoints, incluida la traducción en tiempo de ejecución mediante `POST /v2/projects/{projectId}/translate`, están disponibles en `https://api.gtx.dev`. ### Autenticación Autentícate con una Clave de API en la cabecera estándar `Authorization`. ```bash curl https://api.gtx.dev/v2/projects/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." \ -H "gt-api-version: 2026-10-08.v1" ``` Elige el alcance de clave que se ajuste a tu flujo de trabajo: * **Project** con el prefijo `gtx-api-`: vinculada a un solo Project y utilizable en cualquier entorno, según sus permisos * **Organization** con el prefijo `gtx-org-`: funciona en todos los Projects de la Organization a la que está vinculada, según sus permisos El path determina sobre qué actúa una solicitud: `/v2/projects/{projectId}/...`, sobre el Project; `/v2/orgs/{orgId}/...`, sobre la Organization, y `/v2/context-groups/{groupId}/...`, sobre la Organization propietaria del grupo. Los endpoints de descubrimiento (`GET /v2/orgs` y `GET /v2/projects`) no requieren ningún ID. La clave debe tener acceso al Project o a la Organization seleccionados, por lo que una clave de Project solo funciona en su propio Project. No incluyas Claves de API en los bundles que se despliegan en navegadores ni en dispositivos móviles. (Consulta [Claves de API](/docs/platform/dashboard/reference/api-keys) para saber cómo crear Claves de API y definir su alcance). ### Permisos La mayoría de los endpoints requieren un permiso en la identidad de la solicitud. [List Organizations](/docs/platform/openapi/reference/organizations/list-orgs), [List Projects](/docs/platform/openapi/reference/projects/list-projects) y [Get a Project](/docs/platform/openapi/reference/projects/get-project) no necesitan ningún permiso de recurso más allá del acceso a la Organization o al Project devueltos. Tanto las claves de Organization como las de Project admiten permisos **All** o **Custom** en el Dashboard, limitados a los permisos que el creador puede conceder. El [endpoint de Clave de API de Project](/docs/platform/openapi/reference/projects/create-project-api-key) te permite seleccionar permisos u omitir la selección para conceder todos los permisos de Project que puedas delegar. Los permisos Write no incluyen Read. Las claves de Project no pueden tener permisos de Organization (`org:*`) ni `project:api_keys:write`, por lo que los endpoints que los requieren necesitan una Organization key. Permisos comunes: * `org:projects:create` para crear Projects con `POST /v2/orgs/{orgId}/projects`. * `project:api_keys:write` para crear Claves de API de Project con `POST /v2/projects/{projectId}/api-keys`. * `org:assets:write` para subir fuentes con `POST /v2/orgs/{orgId}/assets`. * `project:files:read` para descargar archivos; leer los metadatos y el estado de los archivos; listar ramas y sus archivos; y leer trabajos. * `project:files:write` para subir archivos de origen y traducciones; sobrescribir traducciones; publicar; crear y actualizar ramas; establecer etiquetas; y mover archivos. * `project:translations:enqueue` para traducir archivos con `POST /v2/projects/{projectId}/files/translate`. * `project:translations:generate` para traducción en tiempo de ejecución. * `project:context:write` para generar contexto. * `org:context:read` para leer Context Groups, su glosario e instrucciones personalizadas, las asignaciones a Projects y las exportaciones. * `org:context:write` para crear, actualizar y eliminar Context Groups y su contenido, importar contenido, y asignar, desasignar y reordenar grupos en los Projects. * `project:write` para actualizar la configuración del Project. ### Control de versiones Envía la cabecera `gt-api-version` en cada solicitud para elegir la versión del contrato de la API. ```bash -H "gt-api-version: 2026-10-08.v1" ``` * Los endpoints cuya página de referencia indica que la cabecera es obligatoria devuelven `400` si no se incluye o si especifica una versión anterior. * Los demás endpoints usan la versión compatible más antigua cuando falta la cabecera y devuelven los errores como texto sin formato en lugar de JSON. Para consultar los endpoints de una versión anterior, selecciónala en el menú de versión de la API, en la parte superior de cualquier página de OpenAPI. ### Solicitudes por lotes Los endpoints por lotes que se indican a continuación devuelven un resultado por elemento, en el mismo orden de la solicitud. * **Escrituras** (subir archivos de origen y traducciones; mover, publicar y sobrescribir archivos; y subir recursos de fuentes) devuelven `200` con `summary` (recuentos de `total`, `succeeded` y `failed`) y `results`, incluso cuando fallan todos los elementos. Un elemento fallido tiene `status: "failed"` y un `error`; los demás elementos se aplican de todos modos. Una solicitud que no supera la validación devuelve `400` y no aplica nada. * **Lecturas** (consultas de archivos, de contenido de archivos y de trabajos) devuelven `200` con `results`. Un elemento que no existe en el Project se marca como `not_found`. Una traducción de archivo que está almacenada pero aún no se ha completado (por ejemplo, durante una pasada de maquetación) se marca como `pending`; vuelve a solicitarla más tarde. Una traducción figura como `not_found` mientras su tarea de traducción no la haya almacenado, así que espera a que termine el trabajo con `GET /v2/projects/{projectId}/jobs/{jobId}` o `POST /v2/projects/{projectId}/jobs/query` antes de leerla. Sin `versionId`, una lectura devuelve la versión completada más reciente de la rama, y solo figura como `pending` mientras no haya ninguna completada. Las consultas de trabajos devuelven el estado de cada trabajo. Otros endpoints por lotes tienen su propia respuesta: poner en cola la traducción de archivos devuelve `202` con los `jobs` creados, y las operaciones de actualizar o insertar del glosario y de las instrucciones personalizadas de Context Management aplican el lote completo o nada, y devuelven `committed` con los `counts` de elementos. ### Límites de metadatos en tiempo de ejecución Para `POST /v2/projects/{projectId}/translate`, un entero positivo en `maxChars` añade una instrucción de longitud a los prompts de traducción compatibles; no es un límite garantizado de la longitud de la salida. Los números no positivos o fraccionarios se ignoran. Los valores de tipo incorrecto hacen que falle la validación de la solicitud. Cada archivo `sourceCode` conserva como máximo cinco entradas de contexto. La API trunca los campos `before` y `after` de cada entrada a 2000 caracteres y su campo `target` a 500 caracteres. Establece `fileFormat` en `MD` o `MDX` para traducir un documento completo proporcionado como una cadena. Las solicitudes de documentos deben usar `dataFormat: STRING` y no pueden incluir `maxChars` ni `sourceCode`. La API divide el documento en fragmentos, añade el contexto de la solicitud a cada fragmento y devuelve una única cadena de documento validada. Si un fragmento falla o el documento final no es válido, falla esa entrada en lugar de devolver una salida parcial. ### Límites de solicitudes La limitación de solicitudes usa ventanas de 60 segundos en dos capas: * **Antes de la autenticación:** cada credencial presentada puede realizar 600 intentos por minuto, incluidas las solicitudes que fallan en la autenticación. Las solicitudes sin credencial omiten esta capa. Al superar el límite se devuelve `429` con `Retry-After: 60` y sin cabeceras `RateLimit-*`. * **Después de la autenticación:** cada grupo de rutas limita las solicitudes por autor de la llamada autenticado, como una Clave de API. Las rutas limitadas sin un autor de la llamada autenticado usan la IP del cliente. Los límites posteriores a la autenticación varían según el endpoint: * **Heavy:** 30 solicitudes/minuto para traducir archivos. * **Medium:** 120 solicitudes/minuto para subir archivos de origen, traducciones y fuentes; sobrescribir traducciones; generar contexto; mover archivos; listar archivos de rama, y publicar. * **Light:** 300 solicitudes/minuto para descargas de archivos. * **Default:** 200 solicitudes/minuto para descubrimiento de Projects y de Organization, creación de Projects y de Claves de API de Project, configuración del Project, ramas, etiquetas, trabajos, metadatos y estado de archivos, traducción en tiempo de ejecución y Context Management. Listar Projects, crear Projects y crear Claves de API de Project comparten un mismo límite. Al superar un límite posterior a la autenticación se devuelve `429` con cabeceras `RateLimit-*`. ### Paginación Los endpoints de listado devuelven una página de resultados con el formato `{ "items": [...], "nextCursor": ... }`. Pasa `limit` (de 1 a 100; 50 por defecto) para definir el tamaño de página. Si `nextCursor` es una cadena, envíalo como `cursor` para obtener la página siguiente; si es `null`, no hay más resultados. Un cursor solo es válido para el listado y los filtros que lo generaron. Cada página se lee de forma independiente, por lo que los elementos que cambien entre solicitudes pueden omitirse o aparecer repetidos. ### Errores Cuando se establece `gt-api-version`, los errores devuelven un cuerpo JSON con un mensaje de `error`. Esto se aplica a todos los errores, incluidos los de JSON mal formado (`400`), cuerpo demasiado grande (`413`) y límite de solicitudes (`429`). ```json { "error": "API key is missing required permission: project:files:write" } ``` Códigos de estado comunes: * `400` para un cuerpo de la solicitud, `query` o versión no válidos. * `401` para una credencial Bearer ausente o no válida. * `402` cuando la cuenta de facturación de la Organization está bloqueada, o sus límites de uso o su saldo de créditos no cubren la solicitud (traducción de archivos y traducción en tiempo de ejecución). * `403` cuando la identidad de la solicitud no tiene permiso o la acción no está permitida en el plan actual. * `404` cuando no se encuentra el recurso. * `409` en caso de conflicto, como la creación de un Project que supera el límite de Projects de la Organization, un nombre de rama que ya está en uso o un cambio de nombre que coincide con un término del glosario o una instrucción personalizada ya existentes. * `413` cuando el cuerpo de la solicitud supera el límite del endpoint o cuando una respuesta de Context Management superaría 1 MiB (solicita un `limit` menor). * `415` cuando falta el `Content-Type` del cuerpo de la solicitud o no es `application/json`. * `429` cuando se excede un límite de solicitudes. * `500` para un error interno del servidor. * `503` cuando el servicio no está disponible temporalmente. Reintenta las respuestas `429` y `503` pasado un tiempo. En el caso de `429`, espera los segundos indicados en la cabecera `Retry-After`. ## Especificación OpenAPI [#openapi-spec] Hay una especificación OpenAPI 3.1 legible por máquinas de la versión más reciente disponible en [`/openapi.json`](/openapi.json), y la de cada versión anterior está en `/openapi/.json`. Impórtala en Postman, Insomnia o en un cliente OpenAPI para generar solicitudes y tipos. Para helpers de endpoint tipados, usa el [cliente `@generaltranslation/api`](/docs/platform/core/reference/api-client). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.