Ir al contenido principal

meshy/relief/image-to-3d

Meshy Relief convierte una foto en una placa en relieve o grabada para impresión 3D o tallado CNC, y entrega un GLB sin textura, un STL y un mapa de profundidad de 16 bits, con tamaño y profundidad de tallado en milímetros.

Desde $0.96/solicitud

Playground

Enviar una solicitud

Inicio rápido

Los ejemplos usan las definiciones públicas de parámetros del endpoint seleccionado. Sustituye la clave de API y los medios de ejemplo, y envía la solicitud desde tu servidor.

SDK e integraciones
POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

Autenticación de API

Guarda la clave de API en la variable de entorno del servidor SPICY_API_KEY. Usa autenticación Bearer y Content-Type: application/json en las solicitudes JSON.

Authorization: Bearer $SPICY_API_KEY
Meshy Relief · Photo to Relief · Resultado de ejemplo
Resultado de ejemploUsar este ejemplo
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "meshy/relief/image-to-3d",
  "input": {
    "bend_axis": "xz",
    "bend_mode": "off",
    "carving_mode": "emboss",
    "image_url": "https://example.com/reference.png",
    "relief_height": "low"
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Generado a partir del esquema de entrada de este modelo: el mismo con el que la API valida cada solicitud.

Parámetros de entrada

Incluye estos campos en el objeto input del cuerpo de la solicitud. Los nombres y tipos coinciden con la API. No supongas un valor predeterminado si no está indicado.

image_urlstringObligatorio

Foto obligatoria JPEG, PNG o WebP de al menos 32 x 32 píxeles y como máximo 20 MB; no hay imagen predeterminada. Un sujeto claro y un fondo sencillo ayudan; la entrada no modifica la tarifa fija.

Valor predeterminado
Sin especificar
Restricciones
minLength:1
contentMediaType:["image/jpeg","image/png","image/webp","image/gif"]
mesh_resolutionintegerOpcional

Cantidad de puntos de la malla a lo largo de la dimensión mayor: 512–1024, con 1024 por defecto. Los valores menores reducen el detalle y el tamaño del archivo, con el mismo precio por relieve.

Valor predeterminado
1024
Restricciones
minimum:512
maximum:1024
bend_anglenumberOpcional

Ángulo de curvatura en grados, de 0 a 360 y con 60 por defecto; úsalo con el modo convex o concave. El ángulo elegido no afecta el costo.

Valor predeterminado
60
Restricciones
minimum:0
maximum:360
bend_axisstringOpcional

xz (predeterminado) curva los lados izquierdo y derecho; yz curva los bordes superior e inferior. El eje tiene efecto al activar la curvatura y no influye en el cobro.

Valor predeterminado
"xz"
Valores permitidos
"xz""yz"
bend_modestringOpcional

off (predeterminado) mantiene la placa plana; convex curva hacia afuera y concave hacia adentro. El modo de curvatura no agrega cargos.

Valor predeterminado
"off"
Valores permitidos
"off""convex""concave"
removal_thresholdnumberOpcional

Umbral de eliminación del fondo de 0.01 a 1, con 0.01 por defecto; actúa cuando remove_base está activado. Los valores mayores recortan más fondo sin modificar el precio.

Valor predeterminado
0.01
Restricciones
minimum:0.01
maximum:1
remove_basebooleanOpcional

Desactivado por defecto; actívalo para solicitar la eliminación del fondo y la placa, conservando el sujeto. El resultado depende de la separación de profundidad y la opción no tiene costo adicional.

Valor predeterminado
false
base_thickness_mmnumberOpcional

Grosor opcional de la placa de 0.1–10 mm; aquí no se especifica un valor numérico predeterminado. Omítelo si activas remove_base; el grosor no cambia la tarifa.

Valor predeterminado
Sin especificar
Restricciones
minimum:0.1
maximum:10
size_mmnumberOpcional

Dimensión larga de la fotografía sobre el relieve, medida en plano antes de curvar: 20–250 mm, con 60 mm por defecto. El tamaño físico no modifica el cargo.

Valor predeterminado
60
Restricciones
minimum:20
maximum:250
carving_depth_mmnumberOpcional

Ajuste directo opcional de profundidad de 0 a 60 mm; si lo omites, relief_height aporta unos 3 mm o 6 mm de profundidad. Cambiar la profundidad no agrega recargos.

Valor predeterminado
Sin especificar
Restricciones
minimum:0
maximum:60
carving_modestringOpcional

emboss es el valor predeterminado y eleva el sujeto sobre la placa; engrave talla hacia adentro las partes más cercanas. Ambos modos tienen el mismo precio.

Valor predeterminado
"emboss"
Valores permitidos
"emboss""engrave"
relief_heightstringOpcional

Elige low (predeterminado, unos 3 mm de profundidad) o high (unos 6 mm); carving_depth_mm sustituye la profundidad predefinida sin cambiar la tarifa.

Valor predeterminado
"low"
Valores permitidos
"low""high"

Seguir la tarea

HTTP 202 significa que la tarea se aceptó, no que haya terminado. Guarda el taskId devuelto y consulta esa tarea. No crees otra mientras esperas el resultado.

Solicitud aceptada
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_create",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.750000"
  }
}

La respuesta de aceptación incluye la estimación para que tu aplicación pueda mostrar el mismo importe en el historial de tareas y en la facturación.

Consultar la tarea
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
  --data-urlencode "taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Empieza consultando cada 2 segundos aproximadamente y ve espaciando los intentos. Párate en un estado final. Si se cae la conexión, consulta el taskId original. Vuelve a crear la tarea solo con la clave de idempotencia y el cuerpo originales.

O recibe el resultado por callback
import { verifyWebhook } from "@spicyapi/sdk";

// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
  const { payload } = verifyWebhook({
    rawBody: req.body,
    timestamp: req.header("X-Webhook-Timestamp"),
    signature: req.header("X-Webhook-Signature"),
    payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
    secret: process.env.SPICY_WEBHOOK_SECRET,
  });
  res.status(200).end();
  void handleFinishedTask(payload);
});

Pasa callBackUrl al crear la tarea y recibirás el registro terminado por POST, sin un bucle de consultas de estado. Cada entrega lleva X-Webhook-Timestamp, X-Webhook-Signature y X-Webhook-Payload-Version. La firma es un HMAC-SHA256 en base64 sobre taskId.timestamp.sha256(body), así que debes verificarla con los bytes originales: si analizas el JSON y vuelves a serializarlo, los bytes cambian y la verificación falla. Las entregas fallidas se reintentan, de modo que el mismo taskId puede llegar dos veces; haz que tu manejador sea idempotente. Responde 2xx primero y haz el trabajo después: un manejador lento se trata como una entrega fallida.

Leer el resultado

Procesa output solo cuando state sea succeeded. Si falla, consulta errorCode, errorMessage y request_id. Los costos y estados de ejemplo no representan una factura real.

Ejemplo de respuesta completada
{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_record",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "meshy/relief/image-to-3d",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.png",
          "mime": "image/png",
          "url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T12:20:08.000Z"
        }
      ]
    },
    "cost": "0.750000",
    "settled": true,
    "createdAt": "2026-08-28T12:00:00Z",
    "completedAt": "2026-08-28T12:00:30Z"
  }
}

Para cada archivo disponible, abre o descarga assets[].url directamente, sin la cabecera Authorization de la API. El enlace firmado expira en expiresAt: vuelve a consultar la tarea para renovarlo mientras el archivo siga dentro del periodo de conservación. Un archivo pendiente o no disponible no trae URL. Trata los enlaces firmados como datos privados.

SDK e integraciones

Usa SpicyAPI en tu app, terminal, asistente de IA o flujo visual. Elige una guía de configuración.

Úsalo en ComfyUI

Instala los nodos de SpicyAPI desde ComfyUI Manager o con el comando de abajo y busca Meshy Relief · Photo to Relief en el lienzo. El nodo tiene las mismas opciones que esta página y muestra su precio antes de ejecutarse.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi