Solicitudes

Una solicitud es una llamada a un modelo. Tiene un id (req_…), un estado, su costo en créditos de API (1000 = 1 USD) y, cuando se completa correctamente, los archivos generados. El mismo objeto se devuelve desde cada endpoint de abajo, para cada modelo.

Buscar un modelo#

El catálogo de los 1,496 modelos es JSON público (no se necesita una clave):

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

Cada fila tiene id, name, lab, category, family, summary, tags, output_kind, docs_url y un objeto price (consulta Precios). GET https://api.doitong.com/v1/models/{model_id} agrega el JSON Schema completo de entrada y salida, los nombres canónicos de los parámetros, las reglas de precio y un ejemplo de entrada. Una category o mode desconocida devuelve 400 invalid_parameter.

Ejecutar un modelo#

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

• El cuerpo es la entrada del modelo, un objeto JSON. Cada página de modelo enumera sus parámetros.
• La entrada se valida antes de cobrar cualquier cosa. Una entrada no válida devuelve 422 invalid_input con el param problemático y no tiene costo.
• ?wait=N (hasta 20 segundos) mantiene la llamada abierta hasta que la solicitud termina o se agota el tiempo.
• ?webhook_url=https://… envía un POST firmado a esa URL cuando termina la solicitud (consulta Webhooks).
• ?storage=permanent o ?storage=temporary elige cuánto tiempo se conservan los archivos de salida; sin este parámetro se aplica la configuración de la cuenta (consulta Dónde se almacenan los archivos).

La respuesta es 202 Accepted mientras la solicitud sigue en proceso y 200 OK cuando terminó durante la espera (o cuando es una repetición, consulta abajo). Los encabezados Location y Doitong-Request-Id contienen la URL y el id de la solicitud.

Estados#

Una solicitud que supera su límite de tiempo falla con el código timeout y se reembolsa: 15 minutos para imágenes, 60 minutos para video, 30 minutos para audio y todo lo demás.

El objeto de solicitud#

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• outputs es igual para todos los modelos: una entrada por cada archivo generado con type (image, video, audio, file o 3d), una url en nuestro almacenamiento, content_type y, cuando se conocen, file_size, width, height, duration.
• output es el objeto de resultado propio del modelo (sus campos se enumeran en cada página de modelo), con las mismas URL.
• storage indica cómo se conservan los archivos: mode (permanent o temporary), bytes almacenados, expires_at (cuándo se elimina un archivo temporal, null para los permanentes) y expired (true una vez que desaparecen los archivos).
• cost.credits es el precio de la llamada en créditos de API (cost.usd en USD), cost.charged es lo debitado del saldo de API y cost.refunded lo que se devolvió. Para un modelo metered, cost.credits es el máximo retenido al inicio (cost.held); cuando la ejecución se completa correctamente, cost.settled indica el costo del uso y el resto del máximo está en cost.refunded (consulta Cobro según el uso).
• Cuando una solicitud falla, error es { "type": …, "code": …, "message": … }.

Leer una solicitud#

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• ?wait=N (hasta 20 segundos) hace long polling: la llamada devuelve la respuesta en cuanto la solicitud es final, o después de N segundos con el estado actual. Repetir esto es la forma más sencilla de esperar un resultado.
• ?logs=1 agrega las líneas del registro de progreso del modelo (las últimas 50) como logs.

Solo puedes leer solicitudes de tu propia cuenta; cualquier otro id devuelve 404 request_not_found.

Enumerar solicitudes#

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

De la más reciente a la más antigua. limit va de 1 a 100 (predeterminado 20); status y model filtran. La respuesta es { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }; pasa cursor=<next_cursor> para la siguiente página.

Cancelar una solicitud#

curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• Cancelada antes de que iniciara el modelo: el estado cambia a canceled, los créditos de API se reembolsan y recibes 200.
• Ya está generando: la cancelación se envía al modelo y recibes 202 con "cancel_requested": true. Si el modelo termina de todos modos, la solicitud se completa normalmente y se cobra.
• Ya es final: 409 not_cancelable (una solicitud que ya está canceled simplemente devuelve 200).

Eliminar los archivos de una solicitud#

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

Elimina ahora nuestras copias de los archivos de salida de la solicitud y detiene su cobro de almacenamiento. La respuesta es el objeto de solicitud con storage.expired: true; sus URL permanecen en el registro, pero dejan de funcionar. Volver a llamarlo no cambia nada (200). Una solicitud que todavía está queued o running aún no tiene archivos: 409 request_active. Requiere models:run.

Idempotencia: reintentar sin pagar dos veces#

Las redes fallan. Para reintentar una ejecución de forma segura, envía un encabezado Idempotency-Key (cualquier cadena de hasta 255 caracteres, única por operación, por ejemplo tu propio id de pedido):

• Misma clave y mismo cuerpo que antes: recibes la solicitud original (200, encabezado Idempotent-Replayed: true) y no se vuelve a cobrar nada.
• Misma clave y cuerpo después de una ejecución que falló antes de llegar al modelo (upstream_error o internal_error al enviar, insufficient_credits, budget_exceeded, too_many_inflight): no se produjo nada ni se cobró nada, por lo que el reintento ejecuta el modelo de nuevo en lugar de devolver el error.
• Misma clave con un cuerpo diferente: 409 idempotency_mismatch.
• Las claves están vinculadas a la clave de API que las envió.

Dónde se almacenan los archivos#

Cada archivo de salida se copia a nuestro almacenamiento antes de marcar la solicitud como succeeded, por lo que las URL de outputs están en nuestros propios hosts y puedes enlazarlas directamente. Tú eliges cuánto tiempo permanecen:

• La configuración de la cuenta se aplica a las nuevas solicitudes: el interruptor "Conservar archivos para siempre" en el panel, o PATCH https://api.doitong.com/v1/account/storage con {"mode": "temporary"}. GET https://api.doitong.com/v1/account lo muestra en storage, junto con los bytes que conservas y la estimación mensual.
• ?storage=permanent|temporary en una ejecución (el argumento storage de la herramienta run de MCP) la anula para esa ejecución.
• Cambiar la configuración nunca afecta los archivos que ya tienes; elimínalos con DELETE /requests/{id}/files.
• Cuando el saldo de API no puede pagar el almacenamiento, no se cobra nada y recibes un correo: haz una recarga en un plazo de 30 días o los archivos conservados se vuelven temporales y se eliminan 7 días después.

En el caso poco frecuente de que falle nuestra copia, la entrada tiene "stored": false y la URL es la original, de corta duración: descárgalo pronto.