Guías principales
Construir una integración confiable con TokenLab
Mantenga bajo control los costos, reintentos, API keys y registros de solicitudes
Una buena integración hace visibles las opciones de precios y modelos, sobrevive a fallos de red comunes y nunca expone una API key en el navegador. Las siguientes prácticas se aplican a las APIs de chat, imagen, video, audio y otras de TokenLab.
Elija modelos con datos actualizados
Los nombres, capacidades y precios de los modelos cambian. Consulte la Models API o las páginas de los modelos en lugar de mantener una lista permanente en el código o la documentación.
Para un nuevo caso de uso:
- Filtre los modelos según la capacidad que necesite su producto.
- Compare sus precios actuales en TokenLab.
- Pruebe un conjunto pequeño con solicitudes de usuario representativas.
- Mantenga el ID del modelo explícito en cada solicitud.
No cambie de modelo de forma silenciosa. Un reemplazo puede alterar la calidad de la salida, el precio, la longitud del contexto, las herramientas disponibles o el soporte de medios.
Establezca un límite superior de costos
Para modelos de texto, limite la salida a la longitud que su producto realmente pueda utilizar. El nombre del parámetro depende de la API y del modelo, así que revise la página del modelo antes de enviar max_tokens o max_output_tokens.
Las instrucciones más cortas no son automáticamente mejores, pero el contexto duplicado y el texto repetitivo siempre añaden tokens de entrada. Mantenga las instrucciones estables de forma concisa y envíe solo el historial necesario para la siguiente respuesta.
Para solicitudes de imagen, video, música, 3D y Worlds, el costo a menudo depende del número de salidas, la duración, la resolución u otra opción de medios. Muestre el costo estimado actual antes de que un usuario confirme una generación costosa siempre que la API pueda proporcionarlo.
Transmita respuestas de texto largas
La transmisión (streaming) muestra la respuesta a medida que llega y evita que el usuario espere a que se complete. Esto no reduce el costo en tokens.
Para un ejemplo completo con configuración de cliente y comprobaciones de finalización, consulte Streaming.
Maneje una desconexión como una respuesta incompleta. No presente una salida parcial como finalizada con éxito, y no repita una solicitud automáticamente cuando hacerlo pueda crear un efecto secundario o un cargo doble.
Reintente solo cuando sea seguro
Reintente las respuestas 429 después de Retry-After o retry_after. Un breve retroceso exponencial (exponential backoff) es apropiado para respuestas 5xx transitorias. Los errores de autenticación, validación, saldo y longitud de contexto requieren un cambio por parte de la aplicación o del usuario; enviar la misma solicitud de nuevo no los solucionará.
Consulte Límites de tasa (Rate limits) para ver un ejemplo de reintento acotado que respeta Retry-After y deshabilita los reintentos duplicados del SDK.
Establezca un límite de reintentos y un límite de tiempo total. Para la creación de medios, guarde el ID de tarea devuelto. Para las solicitudes enumeradas en Retry safely with an idempotency key, envíe una Idempotency-Key, de modo que un reintento tras un tiempo de espera no pueda ejecutar o cobrar la misma solicitud dos veces.
Mantenga las API keys en el servidor
Nunca incruste una API key de TokenLab en JavaScript del navegador, en un paquete de aplicación móvil, en un repositorio público o en un registro visible para el cliente.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)Utilice API keys separadas para desarrollo, producción y aplicaciones independientes. Asigne a cada clave solo los modelos y el límite de gasto que necesite. Revoque una clave inmediatamente si cree que pudo haber sido expuesta.
Mantenga registros de solicitudes útiles
Almacene los identificadores que le permitan conectar una acción del usuario con los registros de uso y soporte:
request_idpara la solicitud de la APItask_idpara la generación asíncronabilling_transaction_idcuando se devuelva- ID del modelo y endpoint
- Su propio ID de usuario, proyecto o trabajo
No registre API keys, tokens de gestión, prompts privados completos, medios privados o URLs firmadas. Los registros de uso en la Console y la Management API son la fuente de los montos facturados; el conteo de tokens de respuesta del modelo por sí solo puede no describir el cargo final.
Diseñe para el trabajo asíncrono
Las APIs de imagen, video, música, 3D y Worlds pueden responder antes de que el resultado esté listo. Guarde el ID de tarea, consulte GET /v1/tasks/{id} y deténgase solo en completed o failed. Una búsqueda de estado fallida no significa que la generación en sí haya fallado.
Consulte Tareas asíncronas y polling para el manejo de cancelaciones, tiempos de espera y solicitudes duplicadas.
Antes del lanzamiento
- Ejecute solicitudes representativas con el modelo exacto y el formato de API que va a implementar.
- Compruebe tanto las respuestas de éxito como las de error común.
- Confirme que el precio mostrado en su producto coincida con el precio actual de TokenLab.
- Haga que las actualizaciones, los tiempos de espera de red y los clics repetidos sean seguros.
- Haga posible rastrear un resultado visible para el usuario hasta su Request ID.