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

Autenticación

Ver como Markdown Actualizado

Toda llamada que ejecute un modelo o lea 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, cuando la creas. Envíala en el encabezado 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 la configuración de almacenamiento models:run (las claves con images:create o videos:create anteriores también funcionan)
Crear una URL de carga models:run o media:upload
Leer solicitudes y la cuenta models:read (una clave que puede ejecutar modelos también puede leer)

Las claves nuevas reciben models:read y models:run de forma predeterminada. Una llamada sin el ámbito correcto 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, el coste se comprueba frente a lo que la clave ya ha gastado mediante esta API (neto de reembolsos). Una ejecución que lo superaría 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 · cuenta
{
  "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 velocidad

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

Encabezado 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 que se restablece la ventana

Si superas el límite, recibes 429 con un encabezado Retry-After (segundos). El sondeo prolongado con ?wait= cuenta como una solicitud por llamada, por lo que esperar es más económico que sondear 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; iníciala de nuevo después de que termine una.