Chat Completions¶

POST /chat/completions handles text generation, multi-turn conversations, and multimodal conversations with image input. It uses OpenAI-compatible messages, choices, and usage structures.

Minimal request¶

curl "$GENESIS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {"role": "system", "content": "You are a precise data assistant."},
      {"role": "user", "content": "Explain data lineage in one sentence."}
    ]
  }'

model and messages are the central request fields. Each message has a role and content; common roles are system, user, and assistant. To preserve conversation context, the application sends the relevant earlier messages again in chronological order.

Common optional parameters¶

Parameter	Purpose
`temperature`	Adjust sampling randomness
`top_p`	Restrict candidate tokens with nucleus sampling
`max_tokens`	Limit the maximum generated tokens
`frequency_penalty`	Reduce the tendency to repeat content
`presence_penalty`	Encourage content not already present
`seed`	Control the random seed when the model supports it
`stream`	Return incremental SSE events when set to `true`

Valid ranges, defaults, and support depend on the model. Avoid changing both temperature and top_p aggressively. When migrating to another model, validate existing parameters in the Debug Playground.

Read the response¶

For a non-streaming response, the generated text is normally in choices[0].message.content, with the stop condition in choices[0].finish_reason. Use usage.prompt_tokens, usage.completion_tokens, and usage.total_tokens for application telemetry and usage reconciliation. Do not assume every model returns the same optional fields.

A finish_reason of length means the response reached its output limit and should not be treated as complete. Increase the permitted output length or reduce the input before trying again.

Image input¶

A vision-capable model can mix text and an image in one user message:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Summarize the main information in this image."},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/image.png"}
    }
  ]
}

Images can use an accessible public URL. The repository reference also documents the data:image/...;base64,... form. Supported image types, size limits, and vision support are model-specific; check the model details and Debug Playground. Image input can count toward input-token usage.

For streaming, see Results, Pagination, and Streaming. For Base URL and key setup, see Endpoints and Authentication.