Skip to main content

Prompt engineering

celeris-1 is a fast, general purpose diffusion model. It performs best when prompts define the task, allowed output format, and an appropriate token limit.

Specify the output format exactly​

State the required output format explicitly:

  • ✅ "Reply with one word: positive, negative, or neutral."
  • ✅ "Reply with JSON only: {name, company, intent}."
  • ✅ "Reply with the number only."
  • ❌ "What do you think the sentiment is?"

Constrained outputs are easier to validate and generally require fewer completion tokens. Avoid open-ended wording when the caller expects a fixed schema or label.

Enumerate the answer space​

When the output is a label, list the valid labels and close the set:

{
  "model": "celeris-1",
  "messages": [
    {"role": "system", "content": "Choose exactly one tool: search, calculator, email, or none. Reply with that tool name only, without reasoning."},
    {"role": "user", "content": "what is 2 + 2?"},
    {"role": "assistant", "content": "calculator"},
    {"role": "user", "content": "what is 14% of 2,300,000?"}
  ],
  "max_tokens": 256,
  "temperature": 0
}
  • Include an escape hatch (none, unknown, other) so the model has a valid answer for inputs outside the set. Otherwise, it may choose the closest label.
  • Specify the number of labels when the response must contain exactly one value.

Put the task in the system message​

Use the system message for the standing instruction and the user message for input data. This keeps the instruction stable and makes it easier to version and evaluate independently from the payload:

{
  "messages": [
    {"role": "system", "content": "Score how well the passage answers the question, 0-10. Reply with the number only."},
    {"role": "user", "content": "Question: ...\nPassage: ..."}
  ]
}

Message roles help distinguish instructions from data, but they do not by themselves prevent prompt injection. Treat untrusted input as untrusted data, constrain available actions, and validate model output before using it.

Set an explicit token budget​

  • Leave headroom in max_tokens. The limit is a generation ceiling, not just the number of tokens visible in the final label or score. A ceiling set too close to the expected answer can stop the model before it emits that answer. Start short structured calls at 256 and tune only after evaluating representative inputs. Completion length affects both latency and cost.
  • Keep prompts concise. Prompt tokens are billed on every call, and shorter instructions leave more room for input data within the context window.
  • Use stop sequences when the format has a clear delimiter, such as a newline.

Make it deterministic​

For classification, extraction, and scoring, use temperature: 0. Add a seed when you need more reproducible sampling:

{"temperature": 0, "seed": 7}

Lower variation makes evaluations and caches more useful. Increase temperature only for tasks that benefit from varied output, such as generating alternative phrasings.

Add examples when needed​

For unusual JSON shapes or domain-specific labels, add one or two compact examples to the system message:

Extract fields as JSON only: {items: [{name, qty}], pickup_time}.
Example: "two flat whites for 8am" -> {"items": [{"name": "flat white", "qty": 2}], "pickup_time": "8:00am"}

Keep examples minimal because they count toward the context window and are billed on every request. Omit them when the instruction is sufficient.

Validate the output, and retry with feedback​

For a strict JSON contract on a non-streaming request, set response_format rather than asking for JSON in the prompt. {"type": "json_object"} guarantees only that the reply is a JSON object, so validate it below either way. Step 1's code-fence mitigation applies only to streaming and prompt-only JSON.

Validate every structured response:

  1. Validate the response against your schema (JSON parse, enum check, range check). If an expected JSON response has a code-fence-shaped wrapper, apply the narrow mitigation in Known issues before parsing.
  2. On failure, retry once with the error appended, e.g. a second user message: Your last reply was not valid JSON. Reply with JSON only.
  3. On a second failure, fall back. Route to your default branch rather than looping.

Bound retries and define a deterministic fallback for invalid output.

Iterate in the Playground first​

Use the Console Playground to test prompts and response formats against the live model. The Use it from code panel provides an equivalent API example.

Next steps​