# api: Referencia de la API URL: https://generaltranslation.com/es/docs/api.mdx --- title: Referencia de la API description: Endpoints públicos de la API de General Translation, autenticación y la especificación de OpenAPI index: true --- La API de General Translation te permite subir contenido de origen y archivos traducidos, descargar traducciones, traducir y poner contenido en cola, gestionar ramas y etiquetas, y consultar el estado del proyecto y de los trabajos. La mayoría de los flujos de trabajo del SDK y la CLI llaman a estos endpoints por ti, pero también puedes llamarlos directamente para automatizaciones personalizadas. Cada endpoint tiene su propia página en esta sección, con parámetros, esquemas y una herramienta interactiva para probar solicitudes. Además, estas páginas incluyen una especificación OpenAPI 3.1 legible por máquina como `openapi.yaml`; impórtala en Postman, Insomnia o un cliente OpenAPI para generar solicitudes y tipos. ## URL base | API | URL base | | -------------------------------------------------------- | ------------------------- | | Endpoints de proyectos y archivos | `https://api.gtx.dev` | | Traducción en tiempo de ejecución (`POST /v2/translate`) | `https://runtime.gtx.dev` | ## Autenticación Autentica cada solicitud mediante una clave de API en la cabecera `x-gt-api-key`. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "x-gt-api-key: gtx-api-..." ``` | Tipo de clave | Prefijo | Notas | | --------------------- | ---------- | --------------------------------------------------------------------------------------------------- | | Proyecto (producción) | `gtx-api-` | Vinculada a un proyecto | | Proyecto (desarrollo) | `gtx-dev-` | Para uso local y en vista previa; los endpoints solo de producción la rechazan | | Organization | `gtx-org-` | Funciona en todos los proyectos; debes enviar `x-gt-project-id` en las rutas con ámbito de proyecto | **Claves de Organization:** Cuando te autentiques con una clave de Organization, incluye el proyecto de destino en la cabecera `x-gt-project-id` para cualquier endpoint con ámbito de proyecto. Consulta [claves de API](/docs/platform/api-keys) para saber cómo crear claves y definir su ámbito. ## Permisos Cada endpoint requiere un permiso en la clave de API. Las claves de organización los configuran explícitamente; las claves de proyecto heredan los valores predeterminados del proyecto. | Permiso | Se usa para | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `project:files:read` | Descargar archivos, información del archivo, estado de traducción, información de la rama, archivos huérfanos, información del proyecto, información del trabajo | | `project:files:write` | Subir archivos y traducciones, diffs, publicar, crear ramas, crear tags, mover archivos | | `project:translations:enqueue` | Poner archivos en cola para traducirlos | | `project:translations:generate` | Traducción en tiempo de ejecución | | `project:context:read` | Leer el estado de generación del contexto | | `project:context:write` | Generar contexto | | `project:write` | Actualizar la configuración del proyecto | ## Control de versiones Envía la cabecera opcional `gt-api-version` para fijar el formato de la respuesta. Si se omite, se usa la versión compatible más antigua. La versión más reciente es `2026-03-06.v1`. ```bash -H "gt-api-version: 2026-03-06.v1" ``` ## Límites de tasa Las solicitudes están sujetas a límites de tasa por clave de API (o IP del cliente) en una ventana de 60 segundos. Los límites varían según el endpoint: | Nivel | Límite | Endpoints | | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Alto | 20 / min | Encolar traducciones | | Medio | 60 / min | Subir, diferencias, contexto, movimientos, huérfanos | | Ligero | 120 / min | Descargar archivos | | Predeterminado | 200 / min | Publicar, ramas, etiquetas, información del proyecto, información del trabajo, información del archivo, estado de la traducción, traducción en Runtime | Si se supera un límite, se devuelve `429`. Las cuotas de tokens de Organization también pueden devolver `429` desde `POST /v2/translate`. ## Errores Los errores devuelven un cuerpo JSON con un mensaje de `error`: ```json { "error": "API key is missing required permission: project:files:write" } ``` | Estado | Significado | | ------ | ---------------------------------------------------------------------------------------------- | | `400` | Cuerpo de la solicitud, query o versión no válidos | | `401` | Falta la clave de API o no es válida | | `403` | La clave de API no tiene el permiso requerido o la acción no está permitida en el plan actual | | `404` | Recurso no encontrado | | `429` | Se superó el límite de solicitudes o la cuota de tokens | ## Próximos pasos * [Claves de API](/docs/platform/api-keys) - Crea y define el alcance de las claves * [Webhooks](/docs/platform/webhooks) - Recibe eventos de traducción * [Configuraciones regionales admitidas](/docs/platform/supported-locales) - Códigos de configuración regional usados en las solicitudes