Logo de X Image SplitterX Image Splitter
Logo de X Image SplitterX Image Splitter

Desarrolladores

Referencia de la API REST

Autentícate, haz peticiones, gestiona errores y pagina, con un ejemplo completo de generación. Todas las operaciones aparecen a continuación.

La API REST está disponible en:

https://ximagesplitter.com/api/v1

Acepta y devuelve JSON. Las páginas de esta sección documentan cada operación y se generan a partir de las mismas definiciones con las que funciona la API. El documento OpenAPI 3.1, legible por máquinas, está en https://ximagesplitter.com/api/v1/openapi.json.

Autenticación

Las operaciones que leen información pública del producto (modelos, precios y el perfil del producto) no necesitan credencial. Todas las demás necesitan una de estas:

  • una API Key que creas en tu cuenta;
  • un token de acceso de OAuth emitido a una Connected App para el recurso https://ximagesplitter.com/api/v1.

Envíala como token bearer:

curl https://ximagesplitter.com/api/v1/account/profile \
  -H "Authorization: Bearer $API_KEY"

Cada operación exige un Scope específico, indicado en su página, como generations:write.

Ejemplo: generar una imagen

Elige un modelo

GET /models lista el modelo disponible (Seedream 5.5) con sus operaciones, opciones, huecos de entrada y límites. GET /models/{modelId} devuelve uno.

curl https://ximagesplitter.com/api/v1/models/seedream-5-5

Consulta el precio

POST /generations/estimate devuelve los créditos que costaría una ejecución, sin cobrar nada.

curl -X POST https://ximagesplitter.com/api/v1/generations/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "modelKey": "seedream-5-5",
    "operation": "text-to-image",
    "prompt": "A lighthouse coast at sunset, wide panorama",
    "options": { "composition": "x-carousel", "aspectRatio": "16:9", "resolution": "2K", "outputCount": 1 }
  }'
{ "appCredits": 10 }

Inicia la generación

POST /generations cobra los créditos e inicia el trabajo. Envía un Idempotency-Key para que una petición reintentada nunca inicie una segunda ejecución de pago.

curl -X POST https://ximagesplitter.com/api/v1/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2a9e-lighthouse-01" \
  -d '{
    "submission": {
      "mode": "image",
      "modelKey": "seedream-5-5",
      "operation": "text-to-image",
      "prompt": "A lighthouse coast at sunset, wide panorama",
      "options": { "composition": "x-carousel", "aspectRatio": "16:9", "resolution": "2K", "outputCount": 1 },
      "assets": []
    }
  }'
{ "creationId": "…", "status": "generating", "remainingCredits": 290 }

Obtén el resultado

Consulta GET /generations/{creationId} hasta que status sea succeeded o failed, o suscríbete a los webhooks generation.completed y generation.failed.

curl https://ximagesplitter.com/api/v1/generations/$CREATION_ID \
  -H "Authorization: Bearer $API_KEY"

Cuando termina correctamente, primaryOutput.url y outputAssets contienen las URL de las imágenes, y splitterLinks contiene un enlace por imagen que la abre en el divisor para su propietario con sesión iniciada. Una generación fallida devuelve sus créditos automáticamente.

Los valores de respuesta anteriores son ejemplos; los precios y saldos dependen de tu cuenta y del catálogo actual. Para añadir imágenes de referencia (gratis, hasta 10), súbelas antes con POST /uploads y pasa el publicUrl devuelto en assets, o pasa directamente cualquier URL https pública.

Errores

Los errores usan los códigos de estado HTTP habituales y un único formato JSON:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Payment is required to continue.",
    "request_id": "…",
    "details": {}
  }
}
EstadoSignificado
400La entrada no es válida. details.issues indica cada campo y su problema.
401La credencial falta, no es válida, ha caducado o se ha revocado. Consulta WWW-Authenticate.
402No hay créditos suficientes para esta generación o mejora de prompt.
403La credencial carece del Scope requerido (insufficient_scope).
404No encontrado, incluidos los recursos que pertenecen a otra persona.
409El Idempotency-Key ya se usó con un cuerpo de petición distinto.
429Demasiadas peticiones. Espera los segundos que indica Retry-After.
5xxUn problema temporal en nuestro lado o en un proveedor de modelos. Reintenta más tarde.

code es estable y puedes basar tu lógica en él; message está pensado para personas. Todas las respuestas, correctas o no, llevan una cabecera x-request-id. Indícala cuando contactes con soporte.

Convenciones

  • Idempotencia. Las operaciones que crean algo que podrías reintentar (una generación, una mejora de prompt, un pago, una solicitud de soporte o de reembolso) aceptan una cabecera Idempotency-Key. La misma clave con el mismo cuerpo devuelve el primer resultado en lugar de actuar dos veces.
  • Paginación. Las listas devuelven { "items": [...], "next_cursor": "…" }. Pasa cursor=<next_cursor> para la página siguiente y limit (hasta 100) para el tamaño de página. next_cursor es null en la última página.
  • Límites de peticiones. Las lecturas, las escrituras y las generaciones tienen cada una su propio límite por minuto. Un 429 te dice cuánto esperar.
  • Trabajo asíncrono. Las generaciones terminan en segundo plano; la API responde en cuanto se acepta el trabajo.
  • Traspasos a la persona. La compra de paquetes de créditos (y los cambios en una suscripción creada antes de que dejaran de venderse) devuelven una URL que el titular de la cuenta abre para pagar o confirmar. A través de la API no se paga nada.