La API Key de Doubao no se genera en la aplicación de Doubao, sino en la consola de Volcano Ark. Muchos equipos se pierden en el primer paso: la buscan en los ajustes de la app de chat o en el centro de facturación. Conviene recordar que Doubao es una familia de modelos, Volcano Ark es la plataforma que los sirve y la clave pertenece a un espacio de trabajo dentro de una cuenta de Volcengine.
Este artículo recorre, en orden, el camino completo para llevar una clave a producción: abrir la cuenta, crear la clave, limitar permisos, confirmar el modelo, diagnosticar errores 401 y rotar credenciales. Los precios y las cuotas se consultan en la consola.
Nota: Doubao, Volcano Ark, Volcengine y ByteDance son marcas o nombres de productos de ByteDance y sus empresas vinculadas. Este artículo es solo una discusión técnica y no implica afiliación, representación ni respaldo de esas compañías. La interfaz, los permisos y las cuotas pueden cambiar; consulta la documentación oficial y la consola.
1. Distingue cuenta, clave, espacio de trabajo y modelo
Cuando una clave falla, casi siempre hay uno de estos cuatro objetos mal alineado:
| Objeto | Dónde está | Para qué sirve | Error habitual |
|---|---|---|---|
| Cuenta de Volcengine | Registro, verificación de identidad, centro de facturación | Determina el saldo, el contrato, la factura y la titularidad de la clave | Usar una cuenta personal para un negocio de empresa y luego no poder cuadrar la factura ni el pago corporativo |
| API Key | Página de administración de API Keys en la consola de Ark | Credencial de identidad en cada llamada | Copiarla con espacios o saltos de línea, o incluirla en el código del frontend |
| Espacio de trabajo | Selector en la esquina inferior izquierda de la consola | Aísla recursos, miembros y permisos | La clave y el endpoint están en espacios distintos y la llamada se rechaza |
| Modelo o endpoint | Lista de modelos y página de inferencia en línea | Define qué modelo se invoca realmente | Mezclar el ID de modelo con un ID de endpoint que empieza por ep- |
Método para recordarlo: la cuenta determina quién paga; el espacio de trabajo determina qué se puede ver; la clave determina con qué identidad se llama; el modelo o endpoint determina qué versión se invoca. Cualquier desajuste suele manifestarse como un 401 o un 404.
2. Abrir Volcano Ark y crear la API Key
Tomando como ejemplo la consola de Volcano Ark, el flujo es el siguiente:
- Registra una cuenta de Volcengine y completa la verificación de identidad. Para uso empresarial conviene hacerlo con la razón social de la empresa, de modo que el contrato, el pago y el encabezado de la factura coincidan.
- Entra en la consola de Volcano Ark, confirma que el servicio está activo y elige la región, por ejemplo norte de China (Pekín).
- Verifica el espacio de trabajo actual en la esquina inferior izquierda. Las cuentas nuevas suelen estar en el espacio predeterminado; para proyectos de equipo conviene crear uno aparte.
- Abre la página de administración de API Keys, elige «Crear API Key» y pon un nombre que indique uso y entorno, por ejemplo
doubao-dev-202610odoubao-prod-202610. - Guarda la clave de inmediato en un gestor de contraseñas o en un servicio de gestión de secretos del servidor. No envíes la clave completa por herramientas de chat ni por correo.
- Crea una clave para pruebas, otra para preproducción y otra para producción; no las compartas. La documentación oficial indica que una cuenta principal puede crear hasta 50 API Keys por defecto.
Un detalle: según la documentación oficial, desde el 17 de septiembre de 2026 las claves nuevas usan un nuevo formato en texto plano; el método de autenticación no cambia y las claves creadas antes siguen siendo válidas. Ambas apariencias son normales; primero confirma a qué espacio de trabajo pertenece la clave.
3. Límites de la clave: espacio de trabajo, modelos permitidos e IP
Una API Key no es una llave maestra de toda la cuenta. La documentación oficial especifica que una clave solo puede acceder a los servicios de modelo y a las aplicaciones del espacio de trabajo donde se creó, sin soporte entre proyectos; si un endpoint se migra a otro espacio, la clave original deja de funcionar.
Al crear la clave, o después, normalmente se pueden aplicar dos restricciones:
- Limitar los modelos disponibles: permitir que la clave llame solo a determinados ID de modelo o endpoints personalizados, para evitar que una sola clave se use con todos los modelos.
- Limitar las IP de origen: configurar una lista blanca de IP reduce el riesgo de que una clave filtrada se use desde otra ubicación.
En la gestión de equipos, conviene dividir las claves por «aplicación + entorno» en lugar de por persona. Cuando alguien deja la empresa solo se desactivan las claves correspondientes, sin afectar a otros servicios; además, los registros de llamadas permiten ver qué clave invocó qué modelo y cuándo. Los espacios de trabajo sirven para aislar proyectos; los permisos de los miembros y las cuotas se rigen por la consola.
4. ID de modelo e ID de endpoint de inferencia: no los mezcles
Volcano Ark ofrece dos formas habituales de llamada:
- Inferencia predefinida: no hace falta crear un endpoint de antemano; el campo
modellleva directamente el ID de modelo, por ejemplodoubao-seed-2-1-pro-260915. El ID suele incluir la fecha de versión y no debe abreviarse de memoria. - Endpoint de inferencia personalizado: se crea en la página de inferencia en línea y el campo
modellleva el ID del endpoint, normalmente con prefijoep-. Es adecuado para despliegues fijos, gestión detallada o modelos ajustados con LoRA. El endpoint debe pasar de «en programación» a «saludable» antes de llamarlo con estabilidad.
La diferencia entre ambos ID no es solo de formato. La documentación oficial indica que, al firmar llamadas con Access Key (AK/SK), el campo model debe contener el ID de endpoint; con una API Key se puede usar el ID de modelo o el de endpoint según la documentación. Algunos modelos o cuentas no tienen habilitada la llamada directa por ID de modelo y devuelven InvalidEndpointOrModel.ModelIDAccessDisabled; en ese caso hay que crear un endpoint personalizado y usar el ID ep-.
Por eso, al crear la clave no es obligatorio vincular un modelo, pero antes de salir a producción hay que confirmar que el modelo está disponible en la cuenta y la región actuales, que la clave tiene permiso para acceder y que el campo model de la solicitud corresponde al método de llamada. La asignación de nombres se rige por la consola y por los precios de modelos del sitio.
5. La clave en variables de entorno
No escribas la clave en el código, en archivos de configuración ni en artefactos empaquetados del frontend. La práctica habitual en el servidor es usar variables de entorno:
# .env solo en la máquina local o en el gestor de secretos, y añadido a .gitignore
export ARK_API_KEY="tu API Key de Volcano Ark"
export ARK_MODEL_ID="doubao-seed-2-1-pro-260915"
# Si usas un endpoint personalizado, cambia a:
# export ARK_ENDPOINT_ID="ep-tu-id-de-endpoint"
En Python, léela con os.environ["ARK_API_KEY"] y no definas un valor por defecto. En contenedores, monta la clave como secreto; en CI/CD, usa variables cifradas; en los registros, guarda solo el prefijo o la huella de la clave. Los navegadores, las apps móviles y los miniprogramas no deben contener la clave: deben pasar siempre por un proxy del backend.
6. Cómo diagnosticar 401, 403, 404 y 429
| Síntoma | Código de error habitual | Causa habitual | Qué hacer |
|---|---|---|---|
| 401 | AuthenticationError |
Clave ausente, incorrecta, desactivada o falta Bearer en la cabecera |
Vuelve a copiar la clave, revisa la cabecera Authorization y confirma que clave y endpoint están en el mismo espacio |
| 403 | AccessDenied |
La clave tiene modelos o IP restringidos, o la cuenta no tiene permiso sobre el recurso | Revisa la lista de modelos de la clave, la lista blanca de IP y los permisos del espacio |
| 404 | InvalidEndpointOrModel.NotFound |
ID de modelo o de endpoint mal escrito, o el recurso no existe en el espacio actual | Copia el ID completo desde la consola y verifica región y espacio |
| 404 | ModelNotOpen |
El modelo aún no está habilitado en la cuenta | Habilita el modelo correspondiente en la consola de Ark |
| 404 | InvalidEndpointOrModel.ModelIDAccessDisabled |
La cuenta no permite llamar directamente con el ID de modelo | Crea un endpoint de inferencia personalizado y usa el ID ep- |
| 429 | RateLimitExceeded.* |
Se superó el RPM/TPM de la cuenta, el modelo o el endpoint | Reduce la concurrencia, aplica retroceso exponencial y solicita más cuota si hace falta |
| 500/503 | InternalServiceError, ServerOverloaded |
Anomalía o sobrecarga del servicio upstream | Espera un momento y reintenta; ten preparado un modelo o canal alternativo |
Orden de diagnóstico: primero el estado HTTP, después el código de error y por último el cuerpo de la solicitud. Con un 401 no sospeches de inmediato del saldo; la falta de saldo suele corresponder a un 403 con AccountOverdueError. Con un 404 tampoco cambies el código primero: vuelve a copiar desde la consola el ID de modelo y el ID de endpoint.
7. Conexión directa o gateway unificado
La conexión directa encaja en equipos que solo llaman a Doubao, pueden completar la verificación de identidad y la recarga por su cuenta, y necesitan contrato y factura de Volcengine. La clave y la Base URL deben usarse en pareja: una clave oficial solo va con https://ark.cn-beijing.volces.com/api/v3, y una clave de gateway solo con la dirección del gateway; mezclarlas suele devolver un 401 directo.
Un gateway unificado encaja en equipos que usan Doubao, DeepSeek y otros modelos a la vez, o que quieren una sola entrada con facturación, cuota y registros unificados. Al elegir gateway conviene confirmar cómo se asignan los nombres de modelo, si la transmisión y las llamadas a herramientas están completas, si la clave admite límites por proyecto, cómo se notifican las incidencias y si las cláusulas de datos cumplen los requisitos. ZSQH AI Gateway es un servicio de acceso independiente de terceros y no tiene relación de afiliación con ByteDance; para probarlo puedes crear una cuenta en la página de registro y consultar el cobro en los precios de modelos.
8. Rotación y tratamiento de filtraciones
La clave debería tener un ciclo de vida como una contraseña, no usarse hasta que falle:
- Crea una clave nueva con los mismos permisos y úsala primero solo en instancias de prueba o despliegue gradual.
- Actualiza la variable de entorno o el gestor de secretos, reinicia el servicio y confirma que las llamadas funcionan.
- Observa durante 24 a 72 horas la tasa de error, la latencia y el consumo. Cuando la estabilidad esté confirmada, desactiva la clave antigua; no la borres de inmediato, mantenla un tiempo para poder revertir.
- Ante cambios de personal, filtraciones de código o aparición de la clave en un repositorio público, desactívala y crea otra al momento; no basta con cambiar la contraseña.
- Revisa el detalle de consumo y los registros recientes para detectar modelos, franjas horarias o IP de origen anómalos.
La documentación oficial también advierte que una clave filtrada permite a terceros consumir tu cuota. Ante una filtración, primero desactiva para contener el daño y después investiga la causa.
Artículos relacionados:
- Guía completa de la API compatible con OpenAI
- Qué es un gateway de API
- Cómo integrar la API de DeepSeek
Preguntas frecuentes
¿Se puede generar la API Key de Doubao dentro de la app de Doubao?
No. La app de Doubao está orientada al público general; la API Key se crea en la página de administración de API Keys de la consola de Volcano Ark.
¿Hay que elegir un modelo al crear la clave?
Normalmente no. La clave es una credencial de llamada dentro de una cuenta o espacio de trabajo; el modelo concreto se indica en el campo model de la solicitud. También se puede limitar en la clave qué modelos o endpoints puede invocar.
La misma clave funcionaba ayer y hoy devuelve 401. ¿Por qué?
Las causas habituales son: clave desactivada o rotada, clave y endpoint en espacios distintos, endpoint migrado, cabecera sin Bearer o estado anómalo de la cuenta. Primero verifica a qué espacio pertenece la clave y luego revisa la cabecera y el espacio de trabajo.
¿Debo usar el ID de modelo o el ID de endpoint que empieza por ep-?
Con inferencia predefinida, el ID de modelo; con endpoint personalizado, el ID ep-; al firmar con Access Key, siempre el ID de endpoint. Si aparece ModelIDAccessDisabled, la cuenta no admite llamadas directas por ID de modelo y hay que crear un endpoint.
¿Qué hago primero si la clave se filtra?
Desactiva o elimina de inmediato la clave filtrada, crea una sustituta y actualiza la configuración del servidor; después revisa consumo y registros. No pierdas tiempo primero rastreando cómo se filtró, porque la cuota puede seguir consumiéndose.
