Autenticación

Crear una clave

Las claves de API se emiten desde un workspace en console.artfical.com, en la página de claves de API. Crear una clave ahí es la única forma de obtenerla; no hay manera de generar o rotar una clave a través de la propia API, y eso es deliberado: crear una clave es una acción sensible y poco frecuente, y ponerla detrás de la propia sesión autenticada de la consola la mantiene fuera del alcance de cualquier cosa que solo tenga acceso a nivel de API.

Una clave se ve así, siempre con el mismo prefijo:

tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

El valor completo de la clave se muestra exactamente una vez, en el momento en que la crea. Después de eso, la consola solo muestra una forma truncada para identificarla (los primeros caracteres y los últimos, con el centro oculto). Si pierde el valor completo, no hay forma de recuperarlo; la única opción es revocar esa clave y crear una nueva. Trate una clave de la misma manera que trataría la contraseña de una base de datos: guárdela en una variable de entorno o en un gestor de secretos, no en el código fuente, y nunca en una aplicación del lado del cliente donde el navegador de un usuario final pudiera leerla.

Enviar la clave en una solicitud

Toda solicitud a /v1/chat/completions y /v1/models debe incluir la clave en un encabezado Authorization estándar, usando el esquema Bearer:

Authorization: Bearer tai-sk-bSL2q4ja-skivx5JVNaJyyDVtKgiBAxuq8yRzsb6-e8

Esta es exactamente la misma forma de encabezado que usa la propia API de OpenAI, por lo que apuntar un cliente existente basado en el SDK de openai hacia tAI suele ser un cambio de una sola línea: configure base_url como https://api.artfical.com/v1 y api_key como su clave de tAI, y el código de solicitud propio del SDK no necesita cambiar.

# Python, using the official openai package
from openai import OpenAI

client = OpenAI(
    base_url="https://api.artfical.com/v1",
    api_key="tai-sk-...",
)

response = client.chat.completions.create(
    model="tai-4.1",
    messages=[{"role": "user", "content": "Merhaba"}],
)
print(response.choices[0].message.content)

Una solicitud a la que le falte el encabezado por completo, o que lo envíe con la forma incorrecta (sin el prefijo Bearer , un valor vacío, una clave que no se puede interpretar), se rechaza de la misma manera que una clave directamente inválida: un 401 con un tipo authentication_error. Consulte Errores para ver la forma exacta de la respuesta.

Workspaces y alcance

Una clave pertenece exactamente a un workspace y solo puede usarse para hacer solicitudes en nombre de ese workspace. No existe el concepto de una clave que abarque varios workspaces, ni una forma de otorgar a una sola clave acceso parcial a solo algunos modelos o a algún nivel de límite de tasa; cada clave de un workspace tiene el mismo acceso a todos los modelos listados en la página Modelos. Si necesita separar el uso o la facturación entre dos proyectos distintos, la respuesta son dos workspaces con sus propias claves, no una clave compartida entre ambos.

El uso realizado con una clave determinada, cantidad de solicitudes, cantidad de tokens y costo estimado, se atribuye a esa clave y es visible en la página de Uso de la consola, dentro del alcance del workspace al que pertenece la clave. Esto es puramente para su propia visibilidad; no afecta cómo se procesa una solicitud.

Expiración

Una clave puede crearse opcionalmente con una fecha de expiración (dentro de 7, 30 o 90 días, o nunca, a elección en el momento de crearla). Una vez que una clave supera su fecha de expiración, toda solicitud hecha con ella se rechaza con el mismo 401 authentication_error que una clave inválida, indistinguible desde fuera. Si las solicitudes hechas con una clave que antes funcionaba empiezan de pronto a fallar con 401, una clave expirada es lo primero que hay que revisar, en la página de claves de API, antes de suponer que se rompió otra cosa.

No hay renovación automática. Una clave próxima a expirar debe reemplazarse por una recién creada; la consola no extiende la vida de una clave existente en el mismo lugar.

Revocar una clave

Una clave puede revocarse en cualquier momento desde la página de claves de API, de forma inmediata e irreversible. Una clave revocada se comporta exactamente igual que una expirada desde el punto de vista de la API: toda solicitud posterior con ella recibe 401. La revocación es la respuesta correcta ante una clave filtrada; no hay forma de rotar el valor secreto de una clave en el mismo lugar, solo de revocar la anterior y crear una nueva que la reemplace.

Qué no otorga una clave por sí sola

Tener una clave de API válida es suficiente para hacer solicitudes de chat completion y listar modelos. No otorga acceso a nada en la interfaz de la consola en sí, ni a la configuración del workspace, la información de facturación, o la actividad de otros miembros; eso está protegido por el propio inicio de sesión basado en sesión de la consola, completamente separado de las claves de API. Una clave de API filtrada es un problema real, ya que permite que alguien haga solicitudes (e incurra en el uso asociado) en nombre de su workspace, pero por sí sola no expone su cuenta de la consola ni permite que alguien inicie sesión como usted.