REST API Reference

The REST API is served at:

https://ximagesplitter.com/api/v1

It accepts and returns JSON. The pages under this section document every operation, generated from the same definitions the API runs on. The machine-readable OpenAPI 3.1 document is at https://ximagesplitter.com/api/v1/openapi.json.

AuthenticationCopy link to this section

Operations that read public product facts (models, prices and the product profile) need no credential. Every other operation needs one of:

• an API Key you create in your account;
• an OAuth access token issued to a Connected App for the https://ximagesplitter.com/api/v1 resource.

Send it as a bearer token:

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

Each operation requires a specific Scope, shown on its page, such as generations:write.

Example: generate an imageCopy link to this section

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

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 }

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 }

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

The response values above are examples; prices and balances depend on your account and the current catalog. To add reference images (free, up to 10), upload them first with POST /uploads and pass the returned publicUrl in assets, or pass any public https URL directly.

ErrorsCopy link to this section

Errors use standard HTTP status codes and one JSON shape:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Payment is required to continue.",
    "request_id": "…",
    "details": {}
  }
}

code is stable and safe to branch on; message is for people. Every response, successful or not, carries an x-request-id header. Quote it when you contact support.

ConventionsCopy link to this section

• Idempotency. Operations that create something you may retry (a generation, a prompt improvement, a checkout, a support or refund request) accept an Idempotency-Key header. The same key with the same body returns the first result instead of acting twice.
• Pagination. Lists return { "items": [...], "next_cursor": "…" }. Pass cursor=<next_cursor> for the next page and limit (up to 100) for the page size. next_cursor is null on the last page.
• Rate limits. Reads, writes and generations each have their own per-minute limit. A 429 tells you how long to wait.
• Asynchronous work. Generations finish in the background; the API returns as soon as the job is accepted.
• Hand-offs. Credit Pack checkouts (and changes to a subscription created before subscriptions stopped being sold) return a URL the account owner opens to pay or confirm. Nothing is paid through the API itself.