Models and usage

List the models you may use, choose one per request, and read what you have spent.

GET /v2/models

Returns the models your account may select, grouped by provider. It needs the same key as POST /v2/decide. Each model carries its display name, its price per million input tokens and per million output tokens in US dollars, and the date the price was last checked. The prices are in this response and nowhere else in these pages.

curl https://director.eposyne.com/v2/models \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

{
  "providers": [
    {
      "id": "<provider id>",
      "display_name": "<name>",
      "models": [
        {
          "id": "<model id>",
          "display_name": "<name>",
          "input_usd_per_million": <number>,
          "output_usd_per_million": <number>,
          "price_verified_at": "<date>"
        }
      ]
    }
  ],
  "default": {"provider": "<provider id>", "model": "<model id>"}
}

• default is the pair Director uses when you choose nothing. It is null when no default is currently available. You can still use any pair in the list.
• A provider that is not set up is not listed.
• The list is what you are allowed to use. It does not promise that the provider is up right now.
• Reading the list does not count toward your request rate.
• Cache the list per key and refresh it after a permission error.

Choosing a model for one request

Add both query parameters to POST /v2/decide. Encode the values: a slash in a model id becomes %2F. Use values from your own GET /v2/models list.

curl -X POST "https://director.eposyne.com/v2/decide?provider=<provider id>&model=<url-encoded model id>" \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

• The choice applies to this request only, including its validation pass.
• Send both parameters or neither. One alone, a repeated parameter, an empty value, an unknown pair, or a pair you may not use is a 400 with "code": "invalid_selection".
• A choice never falls back silently. If the pair cannot answer, you get an error and not a different model.
• The reply names the pair that answered in X-LLM-Provider and X-LLM-Model.

{
  "detail": "Both provider and model are required.",
  "code": "invalid_selection",
  "field": "model"
}

If you choose nothing and no default is available, the call is a 503 with "code": "model_unavailable". Pick a pair from the list.

Setting the output-token cap

Each model has a default output-token cap, listed as max_tokens_default in GET /v2/models. Add max_tokens to POST /v2/decide to set it for one request, with or without a model choice:

curl -X POST "https://director.eposyne.com/v2/decide?provider=groq&model=openai%2Fgpt-oss-120b&max_tokens=4096" \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

• The value is a whole number from 64 to the model's max_tokens_ceiling (16384 unless the model lists less). Anything else, or the parameter twice, is a 400 with "code": "invalid_max_tokens" and the accepted min and max. Director never changes the value for you.
• The cap covers the decision's model call and, with validation on, the validation call. It does not change what Plots and Memory spend.
• A higher cap reserves more of your credits before the call; you are still charged only what the call uses.
• Reasoning models such as GPT-OSS spend part of the cap thinking. If a decision comes back with no change and X-LLM-Finish-Reason: length, the model ran out of tokens before its answer: raise the cap.

{
  "detail": "max_tokens must be an integer from 64 to 16384",
  "code": "invalid_max_tokens",
  "field": "max_tokens",
  "min": 64,
  "max": 16384
}

GET /v2/usage/me

Returns your account's spend for the current month. It needs the same key and does not count toward your request rate.

curl https://director.eposyne.com/v2/usage/me \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

{
  "month": "2026-09",
  "spent_eur": 1.25,
  "cap_eur": 10,
  "remaining_eur": 8.75,
  "resets_at": "2026-10-01T00:00:00Z"
}

Ignore fields you do not recognize.

These figures come from Director's own record of the month. Read them after a decision. Do not subtract the rounded dollar headers from a euro balance. Your credit balance itself is on the credits page of your account.

The usage headers on a decision

A successful POST /v2/decide may carry these headers. They are present when the model backend reported usage, and a missing one is not an error.

Use the headers for per-call logging and tuning. Use GET /v2/usage/me for the account total.