Decision models use the native System One protocol to answer classification, scoring, yes/no, or image-localization questions about text, structured state, or images.

Endpoint and authentication

Find model codes in the decision model catalog.

Quick example

curl -X POST https://51kik.com/decision/v1/systemone \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-review-20260930-001' \
  -d '{
    "model": "jev",
    "state": {
      "order": { "amount": 1280, "currency": "CNY" },
      "customer": { "risk_level": "medium" }
    },
    "questions": {
      "review": {
        "type": "choice",
        "instructions": "Decide whether this order can be approved.",
        "criteria": {
          "approve": "Approve when the risk is acceptable.",
          "reject": "Reject when the risk is unacceptable."
        }
      }
    }
  }'

Request body

System One extension fields outside these platform fields are forwarded using the native protocol. The request body limit is 32 MiB, including JSON, base64 text, and multipart framing.

JSON and multipart requests support single-layer gzip, x-gzip, or zstd compression through Content-Encoding. Both compressed and decoded bodies have a 32 MiB limit; zstd windows are limited to 8 MiB. Official SDKs compress larger requests by default. If the service environment rejects a codec with 415, set compression: false in the SDK.

Question types

Each question must contain type and may contain instructions. The supported types are:

Image input and localization

Images and box are experimental TypeSafe features. Each request using them must include TypeSafe-Danger-Zone-Images: true. Jev 1.13 and 1.14 both accept images; box requires Jev 1.14. Keep using a public model code from the platform catalog in model.

Multipart upload

Uploading the file directly is recommended. The first part must be named request and contain the JSON body. Each asset's part names an image file part. Part names must be non-empty and unique, and every image part must belong to exactly one asset.

curl https://51kik.com/decision/v1/systemone \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  -H 'TypeSafe-Danger-Zone-Images: true' \
  -F 'request={"model":"jev","state":{"photo":"photo-ref-001"},"assets":{"photo-ref-001":{"type":"image","part":"photo"}},"questions":{"package":{"type":"box","instructions":"Locate the package in `photo`."}}};type=application/json' \
  -F 'photo=@photo.jpg;type=image/jpeg'

JSON base64

For JSON requests, use Content-Type: application/json and put the format and raw base64 in the asset:

{
  "model": "jev",
  "state": { "photo": "photo-ref-001" },
  "assets": {
    "photo-ref-001": {
      "type": "image",
      "format": "jpg",
      "data_base64": "<padded base64 of photo.jpg>"
    }
  },
  "questions": {
    "package_visible": { "type": "noul", "instructions": "Is a package visible in `photo`?" }
  }
}

type is optional. format must be png, jpg, or jpeg. Use standard base64 with the required = padding, no whitespace or line breaks, and no data: prefix. If a multipart asset supplies both part and data_base64, part takes precedence.

• Only still PNG/JPEG images are accepted. Each side must be 280–1568 px, and each file may be at most 16 MiB, measured after decoding base64.
• The request body, all images after upstream processing, and the request after expanding every reference each have a 32 MiB limit. Exceeding a limit rejects the entire request.
• Every asset must be referenced in a string value in state, instructions, or criteria. Use a distinct UUID per image to avoid accidental matches in other text. Repeated references add the image again toward the expanded limit.
• box returns top, bottom, left, and right (all from 0 to 1), plus confidence, which is null when the upstream model does not provide it. Pair it with a visibility noul when the target might be absent.
• Image tokens are included in usage.input_tokens and billed at the catalog's input price. Request logs retain image references and metadata, with base64 content omitted.

See the official TypeSafe image documentation and Box documentation for the full rules.

Successful response

The gateway preserves the upstream System One response. A successful response contains at least:

{
  "model": "<resolved-upstream-model>",
  "answers": {
    "review": { "...": "System One answer fields" }
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 18
  }
}

The fields inside each answers entry are native to the selected System One model; clients should not assume a fixed nested shape. usage is used for billing. Input and output token prices are shown in the decision model catalog.

Optional headers

Error response

Errors use the OpenAI-style envelope:

{
  "error": {
    "message": "model is required and must not exceed 128 characters",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}