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

Autenticación

Ver como Markdown Actualizado

Cada 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 se ve como doitong_ seguida de 64 caracteres hexadecimales y se muestra una sola 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 vencida también recibe 401.

Alcances

Cada clave tiene alcances. La API de modelos verifica estos:

Acción Alcance necesario
Ejecutar un modelo, cancelar una solicitud, eliminar los archivos de una solicitud, cambiar la configuración 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 puede ejecutar modelos también puede leer)

Las claves nuevas obtienen models:read y models:run de forma predeterminada. Una llamada sin el alcance 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 (1,000 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 verifica el costo comparándolo con lo que la clave ya ha gastado mediante esta API (menos los reembolsos). Una ejecución que lo excederí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 puede 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 solicitudes

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). La consulta prolongada con ?wait= cuenta como una solicitud por llamada, así que esperar es más económico que consultar rápidamente.

También hay un límite de 10 solicitudes en progreso (queued o running) por cuenta. Iniciar una más devuelve 429 too_many_inflight; iníciala de nuevo después de que termine una.