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/publicEsta 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.
| Herramienta | tool | kind | Cré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
| Method | Path | Permiso |
|---|---|---|
| GET | /capabilities | catalog:read |
| POST | /assets | assets:write |
| POST | /tasks | tasks:write |
| POST | /tasks/batch | tasks:write |
| GET | /tasks | tasks:read |
| GET | /tasks/{task} | tasks:read |
| GET | /assets/{asset} | tasks:read |
| GET | /usage | tasks: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.