Ir al contenido
Español (España)
Obtener clave de API
Guía de la API

Autenticación

Ver como Markdown Actualizado

Toda llamada que ejecuta un modelo o lee tus solicitudes necesita una clave de API. El catálogo (GET /models, GET /categories), POST /quote y el documento OpenAPI son públicos.

Claves de API

Crea y revoca claves en https://doitong.com/developers/dashboard#keys. Una clave tiene el formato doitong_ seguido de 64 caracteres hexadecimales y solo se muestra una vez, al crearla. Envíala en la cabecera Authorization:

terminal
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"

X-API-Key: <key> también funciona.

Una solicitud sin clave recibe 401 con el código missing_api_key; una clave desconocida, revocada o caducada también recibe 401.

Ámbitos

Cada clave tiene ámbitos. La API de modelos comprueba estos:

Acción Ámbito necesario
Ejecutar un modelo, cancelar una solicitud, eliminar los archivos de una solicitud, cambiar el ajuste de almacenamiento models:run (las claves con el antiguo images:create o videos:create también funcionan)
Crear una URL de carga models:run o media:upload
Leer solicitudes y la cuenta models:read (una clave que pueda ejecutar modelos también puede leer)

Las claves nuevas obtienen models:read y models:run de forma predeterminada. Una llamada sin el ámbito adecuado recibe 403 con el código insufficient_scope.

Presupuestos de créditos

Una clave puede tener su propio presupuesto en créditos de API (1000 créditos de API = 1 $), establecido por el propietario de la cuenta: un presupuesto total, un presupuesto diario (últimas 24 horas) o ambos. Antes de cobrar una ejecución, se comprueba el coste frente a lo que la clave ya ha gastado mediante esta API (neto de reembolsos). Una ejecución que superaría el límite se rechaza con 402 budget_exceeded y no se cobra nada.

Una clave sin presupuesto puede gastar hasta el saldo de API. Por separado, una ejecución que el saldo de API no pueda cubrir recibe 402 insufficient_credits con un top_up_url.

GET https://api.doitong.com/v1/account muestra el saldo de API y el presupuesto restante de la clave (ambos en créditos de API):

200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}

budget_remaining es null cuando la clave no tiene un presupuesto propio.

Límites de frecuencia

Cada clave puede realizar 3600 solicitudes por hora, salvo que su límite se haya establecido de otra forma. Toda respuesta autenticada incluye el estado actual:

Cabecera Significado
X-RateLimit-Limit Solicitudes permitidas en la ventana actual
X-RateLimit-Remaining Solicitudes restantes en la ventana actual
X-RateLimit-Reset Hora Unix en la que se reinicia la ventana

Si superas el límite, recibes 429 con una cabecera Retry-After (segundos). La consulta prolongada con ?wait= cuenta como una solicitud por llamada, por lo que esperar es más barato que consultar rápidamente.

También hay un límite de 10 solicitudes en curso (queued o running) por cuenta. Iniciar una más devuelve 429 too_many_inflight; vuelve a iniciarla cuando termine una.