# 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 Todos los endpoints requieren una credencial Bearer en la cabecera estándar `Authorization`. La referencia de endpoints indica si una operación acepta una clave de API, un token de acceso de usuario de OAuth 2.1 o ambos. ```bash curl https://api.gtx.dev/v2/project/info/PROJECT_ID \ -H "Authorization: Bearer gtx-api-..." ``` Usa el tipo de clave correcto: * **Project (desarrollo)** con el prefijo `gtx-dev-`: para uso local y de vista previa; los endpoints exclusivos de producción la rechazan * **Project (producción)** con el prefijo `gtx-api-`: vinculada a un solo Project * **Organization** con el prefijo `gtx-org-`: funciona en todos los Projects. La mayoría de los endpoints con alcance de Project requieren `gt-project-id`. `GET /v2/project/info/{projectId}` sigue requiriendo esa cabecera y comprueba que los dos ID coincidan. `POST /v2/projects/{projectId}/api-keys` usa en su lugar su parámetro de path. Los endpoints con alcance de Organization, como `POST /v2/orgs/{orgId}/projects`, usan la Organization del path y requieren que la credencial tenga acceso a ella. (Consulta [API keys](/docs/platform/dashboard/reference/api-keys) para saber cómo crear claves de API y definir su alcance). Las aplicaciones OAuth usan el flujo de Authorization Code con Proof Key for Code Exchange (PKCE). Descubre el servidor de autorización en `https://dash.generaltranslation.com/.well-known/oauth-authorization-server/api/auth`, solicita únicamente los scopes que tu aplicación necesita y envía el token de acceso de usuario resultante en la misma cabecera de portador. El token está limitado tanto por los scopes concedidos como por el acceso actual del usuario a la Organization o al Project de destino. ### Permisos Cada endpoint requiere un permiso en la identidad de la solicitud. Las Organization keys configuran los permisos explícitamente. Las claves de Project creadas en el Dashboard usan los valores predeterminados de su tipo de clave; las claves creadas mediante la API de Organization pueden tener menos permisos porque se limitan a los que la identidad de la solicitud puede delegar. Los tokens de acceso de usuario de OAuth deben incluir el scope correspondiente, y el usuario que ha iniciado sesión debe seguir teniendo ese permiso. Permisos comunes: * `org:projects:create` para crear proyectos 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, información del proyecto 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. * `project:write` para actualizar la configuración del proyecto. ### 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 Las solicitudes están sujetas a límites de solicitudes por clave de API o IP del cliente en una ventana de 60 segundos. Los límites varían según el endpoint: * **Heavy:** 30 solicitudes/minuto para poner traducciones en cola. * **Medium:** 120 solicitudes/minuto para cargas, diffs, contexto, movimientos, archivos huérfanos y publicación. * **Light:** 300 solicitudes/minuto para descargas de archivos. * **Default:** 200 solicitudes/minuto para creación de proyectos y de claves de API del proyecto, ramas, etiquetas, información del proyecto, información del trabajo, información del archivo, estado de la traducción y traducción en runtime. Superar un límite devuelve `429`. Las cuotas de tokens de Organization devuelven `402` desde `POST /v2/translate`. ### Errores Los errores de aplicaciones autenticadas 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. Los errores de análisis, límite de payload y límite de solicitudes pueden devolver texto sin formato antes de que se ejecute la autenticación. ```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. * `413` cuando el cuerpo de la solicitud supera el límite del endpoint. * `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. ## 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. Las herramientas de JavaScript también incluyen el snapshot de OpenAPI que se usó para generar la versión instalada de su SDK. Ese snapshot incluido puede diferir del contrato alojado actual: * Ejecuta [`npx gt api --spec`](/docs/cli/reference/commands/api) con `gt` 2.20.0 o posterior. * Importa `generaltranslation/api/openapi.json` desde `generaltranslation` 9.2.0 o posterior. * Importa `@generaltranslation/api/spec/openapi.json` desde el SDK generado standalone. 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/translation/translate-runtime - /docs/platform/openapi/reference/project/create-project ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.