HANSTUDIO API · v1

Imágenes y vídeo para tu producto

Una API para archivos privados, imágenes, vídeo y tareas por lotes.

Modo actual: … · El modo demo devuelve muestras sin procesamiento real.

Inicio rápido

Inicia sesión y crea una clave API. Guárdala en tu servidor. Sube una imagen, crea una tarea y consulta su ID.

https://ai.hanrouter.com/api/v1/public

Esta es la dirección configurada; usa tu dominio HTTPS público en producción. Envía Accept: application/json.

# Upload a private asset
curl "https://ai.hanrouter.com/api/v1/public/assets" \
  -H "Authorization: Bearer $HANSTUDIO_API_KEY" \
  -H "Accept: application/json" -F "file=@product.png"

# Use the returned asset id, then create a task
curl "https://ai.hanrouter.com/api/v1/public/tasks" \
  -H "Authorization: Bearer $HANSTUDIO_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
  "kind": "image",
  "tool": "remove-background",
  "prompt": "Remove the background from this product image.",
  "ratio": "1:1",
  "reference_id": "ASSET_UUID",
  "request_key": "NEW_REQUEST_UUID"
}'

# Poll the returned task id every 5–20 seconds
curl "https://ai.hanrouter.com/api/v1/public/tasks/TASK_UUID" \
  -H "Authorization: Bearer $HANSTUDIO_API_KEY" -H "Accept: application/json"

Sustituye los ID de ejemplo. request_key debe ser un UUID. No publiques claves en el navegador.

Funciones disponibles

El catálogo sigue la configuración del servidor. Los créditos son precios del sitio. La disponibilidad depende de permisos y configuración.

HerramientatoolkindCréditos base

Consulta capabilities para los campos requeridos. Las máscaras deben coincidir con el original. Los editores locales son independientes. Consulta OpenAPI para parámetros y límites.

Endpoints

MethodPathPermiso
GET/capabilitiescatalog:read
POST/assetsassets:write
POST/taskstasks:write
POST/tasks/batchtasks:write
GET/taskstasks:read
GET/tasks/{task}tasks:read
GET/assets/{asset}tasks:read
GET/usagetasks:read

Sube multipart/form-data con file: JPEG, PNG o WebP, máximo 10 MB. Las tareas usan JSON. Los lotes admiten 1–10 tareas y un request_key; errores de validación o saldo revierten el lote.

{
  "request_key": "BATCH_REQUEST_UUID",
  "items": [
    {
      "kind": "image",
      "tool": "remove-background",
      "prompt": "Remove the background from this product image.",
      "ratio": "1:1",
      "reference_id": "ASSET_UUID"
    }
  ]
}

Tareas, créditos y resultados

queued → processing → completed / failed / needs_review

HTTP 202 reserva créditos. Reutilizar request_key devuelve la tarea original sin otro cargo. Cantidad, duración y cada tarea del lote afectan al coste. Los fallos definitivos se reembolsan; los inciertos requieren revisión.

Consulta cada 5–20 segundos hasta el estado final. Usa result/results para imágenes, resultText para texto y enlaces para OCR. Los archivos privados requieren Bearer; los enlaces pueden caducar en una hora. v1 usa consultas sin callbacks.

{
  "id": "TASK_UUID",
  "status": "completed",
  "kind": "image",
  "mode": "live",
  "progress": 100,
  "cost": 20,
  "result": "https://cdn.example/output.png",
  "results": [
    "https://cdn.example/output.png"
  ],
  "resultText": null
}

Todas las claves comparten 60 peticiones por minuto; las subidas tienen un límite adicional de 30. La API y el sitio comparten créditos.

Errores y diagnóstico

401 · Clave inválida, caducada o revocada
403 · Sin permiso o cuenta desactivada
404 · Recurso inexistente o de otra cuenta
422 · Parámetros incorrectos, archivos ausentes o saldo insuficiente
429 · Límite alcanzado; respeta Retry-After

Los errores incluyen message/errors. Las respuestas llevan X-Request-ID para soporte. Los registros excluyen claves, imágenes y descripciones.