Saltar al contenido principal

Estimaciones asíncronas

Una estimación con fotos puede tardar de 10 a 30 segundos. Con mode: async, la petición responde 202 de inmediato y la estimación termina en segundo plano. Léela después con GET /v1/estimates/{id}, o deja que un webhook te avise cuando esté lista.

mode vale sync por defecto. El modo asíncrono funciona con texto, conversaciones, fotos y seguimientos, y cuesta los mismos créditos.

Envía la petición​

curl https://api.wfskills.com/v1/estimates \
  -H "Authorization: Bearer $HOMETOWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode": "async", "input": {"text": "The fence in the back yard", "images": [{"data": "<base64>"}]}}'

La validación, la revisión de contenido y la revisión de créditos ocurren antes del 202, así que sus errores responden de inmediato, igual que en modo síncrono. La respuesta es 202 con la estimación en status: processing. Su id es definitivo, y la cabecera X-Credits-Held dice cuántos créditos quedan apartados para ella.

{
  "id": "est_01J9Z6X1M4QK2V7H8T3R5N0BCD",
  "object": "estimate",
  "status": "processing",
  "environment": "live",
  "region": "US-MS",
  "currency": "USD",
  "locale": "en-US",
  "locale_fallback": null,
  "task": null,
  "scope": null,
  "labor": null,
  "price": null,
  "calendar": null,
  "steps": [],
  "extras": [],
  "unpriced": [],
  "question": null,
  "usage": {
    "model_calls": 0,
    "credits": 0
  },
  "metadata": {},
  "created_at": "2026-10-09T15:04:05+00:00"
}

Enviar la misma petición otra vez con el mismo Idempotency-Key devuelve este primer 202, no el estado actual. Lee la estimación con GET para ver cómo va.

Obtén el resultado​

Casi todas las estimaciones terminan en menos de un minuto. Usa una de estas dos opciones:

  • Escucha estimate.completed y estimate.failed en un endpoint de webhook. El evento trae la estimación completa en data.object.
  • Consulta GET /v1/estimates/{id} cada pocos segundos hasta que status sea priced, needs_detail, unsupported, unclear o failed.

Lo que pagas​

Los créditos se apartan cuando se acepta la petición. Se gastan cuando la estimación termina con una respuesta (priced, needs_detail, unsupported o unclear) y se devuelven si falla. Una llave de prueba no aparta nada.

Cuando una estimación falla​

Una estimación fallida tiene status: failed, un error con code y detail, y no cuesta nada.

error.codeSignificado
model_unavailableEl estimador no respondió a tiempo. Envía la petición otra vez con un Idempotency-Key nuevo.
unsupported_in_regionEl trabajo no se cotiza en la región.
internal_errorAlgo falló del lado de Hometown. Menciona el id de la estimación si escribes a soporte.

Una estimación que sigue en processing 15 minutos después de la petición falla con model_unavailable en los 5 minutos siguientes.

Pruébalo en el sandbox​

Con una llave de prueba, sandbox:async responde 202 y termina como priced en segundos, y sandbox:failed termina como failed. Las dos responden 202 diga lo que diga mode, y envían su evento a los endpoints de prueba que escuchan estimate.completed o estimate.failed. Consulta Entradas del sandbox.

Última actualización en