Documentación de la APIAutenticación e idempotencia
Claves de API, ámbitos, identificadores de petición y reintentos seguros
Autenticación bearer
Crea y revoca claves en Ajustes → Claves API. El secreto se muestra una sola vez. Envíalo en la cabecera estándar:
Authorization: Bearer sd_YOUR_KEYSolo se acepta la cabecera Authorization. No se admiten credenciales en la
cadena de consulta ni X-API-Key. Una clave ausente, inválida, caducada o
revocada devuelve 401 UNAUTHORIZED. Una clave válida sin el ámbito del endpoint
devuelve 403 FORBIDDEN.
Ámbitos
| Ámbito | Permite |
|---|---|
images:generate | crear trabajos de generación |
images:edit | crear trabajos de edición |
images:convert | crear trabajos de conversión |
jobs:read | leer trabajos de la misma cuenta |
credits:read | leer el saldo actual |
Usa claves restringidas distintas por aplicación y por entorno. Revocar una clave no afecta a los trabajos ya creados en la cuenta.
Idempotencia
Los tres endpoints POST exigen un Idempotency-Key de entre 8 y 255
caracteres. Repetir el mismo endpoint con la misma clave y la misma petición
canónica devuelve el trabajo original sin reservar créditos otra vez. Reutilizar
la clave con contenido distinto devuelve 409 IDEMPOTENCY_CONFLICT.
En las peticiones multipart, los bytes de la imagen de origen forman parte de la identidad. Cambiar la imagen subida manteniendo la clave es, por tanto, un conflicto.
Identificadores de petición
Toda respuesta incluye X-Request-Id. Los cuerpos de error lo repiten en
error.request_id. Estos identificadores se pueden guardar sin riesgo en los
registros de la aplicación.