Start alignment
Start an asynchronous alignment for a model. Alignment learns from annotated training examples and selects improved instructions using the model's test split.
Each question must have string instructions for alignment. The more flexible
inference contract also permits omitted, null, or other JSON instructions, but
those must be replaced with strings before aligning. Criteria descriptions may
remain structured objects or arrays.
The endpoint returns 202 Accepted. Poll the URL in the Location response
header for progress.
/v1/models/{modelId}/alignmentsAuthorization
Send a Modaic bearer token in the Authorization header.
Parameters
A key between 8 and 255 characters. Reuse it only when retrying this exact request.
Model repository ID. Repository write access is required.
Branch to align and, when the run improves the model, update.
Current branch head, from 7 to 128 characters. The request returns
409 source_commit_conflict if the branch has advanced.
Optional. May contain maxMetricCalls, a positive integer up to 1,000,000:
the metric-call budget for the run. Each evaluation of one example under
one candidate is a decision at the model's rate. When maxMetricCalls is
omitted, the API sizes the budget at launch from the validation split: one
pass over it for the seed instructions, four full re-evaluations of
accepted candidates, and 18 proposals at twice the reflection minibatch.
This is the recommended default, because the optimizer scores the seed and
every accepted candidate on the whole split and a fixed number starves
large datasets. The launch log records the budget that applied. The
optimizer checks the budget between iterations, so a run can finish a few
calls past it; the final validation pass on the winner is billed on top.
Optional reflection settings: model, positive minibatchSize up to 10,000,
and integer seed from 0 to 2,147,483,647.
Request example
{
"branch": "main",
"sourceCommitSha": "df5a6fb2d67e4ce6a6ea9d43146d53a4d43f6d37",
"reflection": {
"seed": 42,
"minibatchSize": 8
}
}
Response
Alignment ID.
New commit when the alignment improves the model; otherwise null.
On completion, includes improved, the best candidate instructions, initial
and best scores, token usage, optional validation metrics, and the saved
artifact path.
Live progress with a stage, elapsed time, and—when available—metric-call,
iteration, candidate, and score counters.
Job-level error with code and message.
If the run improves the model, Modaic increments its checkpoint, commits the optimized instructions and alignment artifact, then starts a batch decision at that exact commit for all examples. If it does not improve the model, no model commit is created.