# 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 runtime mediante `POST /v2/translate`, están disponibles en `https://api.gtx.dev`. ### Autenticación Autentícate con una API Key en la cabecera estándar `Authorization`. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` 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 En los endpoints con alcance de Project que incluyen un ID del Project en el path, ese ID determina el Project. Si se envía la cabecera opcional `gt-project-id`, debe coincidir; de lo contrario, la solicitud falla con `403`. Si el path no indica un destino, las claves de Project usan el Project al que están vinculadas y las claves de Organization deben enviar `gt-project-id`. El descubrimiento de Projects y Organizations no requiere indicar un Project de destino. Las rutas con alcance de Organization que indican un destino en el path usan esa Organization, y las rutas de Context Group (`/v2/context-groups/{groupId}`) usan la Organization propietaria del grupo. Las cabeceras de API Key heredadas siguen siendo compatibles y tienen prioridad sobre la cabecera Bearer. No incluyas API Keys en los bundles que se despliegan en navegadores ni en dispositivos móviles. (Consulta [API Keys](/docs/platform/dashboard/reference/api-keys) para saber cómo crear API Keys 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/project/list-orgs), [List Projects](/docs/platform/openapi/reference/project/list-projects) y [Get Project information](/docs/platform/openapi/reference/project/project-info) 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/project/create-api-key) te permite seleccionar permisos u omitir la selección para conceder todos los permisos de Project delegables. Las concesiones explícitas de HTTP Write no incluyen implícitamente Read. Los endpoints de Context Management requieren permisos de Organization, por lo que necesitan una Organization key; las claves de Project no pueden llamarlos. 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`. * `project:files:read` para descargar archivos y leer información de archivos, el estado de la traducción, información de la rama, archivos huérfanos e información del trabajo. * `project:files:write` para subir archivos, traducciones y recursos; enviar diffs; publicar; crear rama y etiqueta; y mover archivos. * `project:translations:enqueue` para poner archivos en cola para su traducción. * `project:translations:generate` para traducción en runtime. * `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 opcional `gt-api-version` para fijar el formato de la respuesta. ```bash -H "gt-api-version: 2026-03-06.v1" ``` Si omites la cabecera, se usará la versión compatible más antigua. La versión más reciente es `2026-03-06.v1`. ### Límites de metadatos en tiempo de ejecución Para `POST /v2/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 API Key. 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 poner traducciones en cola. * **Medium:** 120 solicitudes/minuto para cargas, diffs, generación de contexto, movimientos, archivos huérfanos y publicación. * **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, ramas, etiquetas, información del Project, información del trabajo, información del archivo, estado de la traducción, traducción en runtime y Context Management. El descubrimiento de Projects y de Organization y la creación de Projects/claves comparten un mismo límite de solicitudes. Al superar un límite posterior a la autenticación se devuelve `429` con cabeceras `RateLimit-*`. Las cuotas de tokens de Organization devuelven `402` desde `POST /v2/translate`. ### 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 Los errores devuelven un mensaje de `error`. A partir de la versión de la API `2026-02-18.v1`, el cuerpo es JSON; las versiones anteriores, incluida la predeterminada que se usa cuando no se envía la cabecera `gt-api-version`, devuelven el mensaje como texto sin formato. 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 se excede la cuota de tokens de Organization (`POST /v2/translate`). * `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 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). * `425` cuando un archivo traducido solicitado aún se está procesando. * `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 `425`, `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 disponible en [`/openapi.json`](/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). ## Secciones de referencia - /docs/platform/core/reference/api-client - /docs/platform/openapi/reference/files/upload-source - /docs/platform/openapi/reference/context/generate-context - /docs/platform/openapi/reference/context-management/list-groups - /docs/platform/openapi/reference/translation/translate-runtime - /docs/platform/openapi/reference/project/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.