Genesis API Quickstart

This quickstart makes one non-streaming chat request through Genesis’s OpenAI-compatible API. You need three values: a Base URL, a Genesis API Key, and a model ID.

Gather the connection details

  1. In Genesis, open Models, choose a chat-capable model, and copy the model ID from its details.

  2. Issue a Genesis API Key for a service account in Credential Management. If your deployment provides local key creation under Genesis Keys, you can instead create one there after setting its model scope, quota, rate limits, and lifetime.

  3. Open the Genesis Use page and copy the Base URL. It normally includes /v1; do not append a second version segment.

  4. Verify that the Key can access the selected model. Store the complete Key in a secret manager or environment variable because the complete value might be shown only when the Key is created or rotated.

The commands below contain placeholders. Replace them with the values from your console:

export GENESIS_BASE_URL='https://<genesis-host>/<path>/v1'
export GENESIS_API_KEY='<your-genesis-api-key>'
export GENESIS_MODEL='<model-id>'

Never put the real Key in source code, a shared shell-history file, or a Git repository.

Check the model before calling it

List the models available to the current Key. This request tests the Base URL, authentication, and model authorization together:

curl --fail-with-body --silent --show-error \
  "$GENESIS_BASE_URL/models" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

A successful response contains the available models in data. Find the id you intend to call and make sure it exactly matches GENESIS_MODEL. Model availability and Key scope can change, so avoid relying indefinitely on an unchecked hard-coded catalog.

Send a chat request

curl --fail-with-body --silent --show-error \
  "$GENESIS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$GENESIS_MODEL\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"Explain data lineage in one sentence.\"
      }
    ],
    \"stream\": false
  }"

The generated text is normally in choices[0].message.content, and token consumption is reported in usage. For application monitoring, record the HTTP status, any request identifier returned by the service, model ID, latency, and usage. Never log the Key.

Use the Python SDK

Genesis supports the common OpenAI SDK calling pattern. Install the SDK:

python -m pip install openai

Create quickstart.py:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GENESIS_API_KEY"],
    base_url=os.environ["GENESIS_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["GENESIS_MODEL"],
    messages=[
        {"role": "user", "content": "Explain data lineage in one sentence."},
    ],
)

print(response.choices[0].message.content)
print(response.usage)

Run it:

python quickstart.py

For an existing OpenAI SDK application, migration usually means pointing base_url to Genesis and replacing the API Key. The selected Genesis model must still support the endpoint you call.

Troubleshooting

Symptom

What to check

401 or an authentication error

The request uses Authorization: Bearer; the Key is complete and active; the credential is not a token from another product

404 or an invalid path

The Base URL came from Use and /v1 was not appended twice

Model unavailable or forbidden

GET /models returns that model and the Key’s model scope includes its ID

429

The Key has reached a concurrency, RPM, TPM, or quota limit; retry with exponential backoff instead of immediately replaying requests

Unsupported parameter

Confirm the capability in the model details and reproduce the request with the same model in Debug

In production, set network timeouts and use bounded exponential backoff for retryable failures. Do not automatically retry deterministic authentication or validation errors. To investigate a specific call, filter the Genesis Logs page by time, Key, model, or status.

Next steps