Examples

Chat Completion

curl https://msg.hidoba.com/v3/chat/completions \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      { "role": "user", "content": "Reply with exactly: hello" }
    ],
    "max_completion_tokens": 32
  }'

Streaming Chat Completion

curl -N https://msg.hidoba.com/v3/chat/completions \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      { "role": "user", "content": "Write a two-line poem about rain." }
    ],
    "stream": true,
    "max_completion_tokens": 80
  }'

Responses API

curl https://msg.hidoba.com/v3/responses \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "input": "Explain SPLADE in one sentence.",
    "max_output_tokens": 80
  }'

GitHub Character

curl https://msg.hidoba.com/v3/chat/completions \
  -H "Authorization: Bearer $HIDOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      { "role": "user", "content": "How should I start practicing today?" }
    ],
    "max_completion_tokens": 120,
    "metadata": {
      "hidoba": {
        "character": "github:partner/Coach",
        "character_params": {
          "person_name": "Alex"
        }
      }
    }
  }'

Inline Character With RAG Settings

RAG settings belong in character/server config, not in request-level metadata.hidoba.rag.

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "What should I remember from the knowledge base?" }
  ],
  "max_completion_tokens": 160,
  "metadata": {
    "hidoba": {
      "character": {
        "parameters": {
          "name": "Mira",
          "language": "en",
          "person_name": "Alex",
          "robot_name": "Mira",
          "name_colon": "Mira:",
          "conversation_prefix": "",
          "interruption_message": "",
          "easy_questions": [],
          "difficult_questions": [],
          "voice": null,
          "greetings": [],
          "max_new_tokens": 128,
          "rag_index_required": "v2/partner/profile/collection",
          "llm_texting_rag_retrieve_max_tokens_override": 1200,
          "texting_rag_rewrite_enabled": true
        },
        "personality": "You are {{ robot_name }}. Use the provided context when it is relevant."
      }
    }
  }
}

Reasoning Effort

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Think briefly, then answer with one paragraph." }
  ],
  "reasoning": { "effort": "low" },
  "max_completion_tokens": 200
}

Use none to turn reasoning off:

{
  "reasoning": { "effort": "none" }
}

Use a token budget when the model supports it:

{
  "reasoning": { "max_tokens": 1024 }
}

Fallback Model

{
  "model": "google/gemini-2.5-flash",
  "fallback_model": "qwen/qwen3.6-27b",
  "messages": [
    { "role": "user", "content": "Give me one concise product idea." }
  ],
  "max_completion_tokens": 100
}

fallback_model is a Messages API v3 routing instruction. It is removed from the provider-visible payload and converted into Bifrost fallback routing.

Invalid Metadata

This request is rejected because metadata.hidoba.rag is not accepted:

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "metadata": {
    "hidoba": {
      "rag": { "enabled": true }
    }
  }
}

Configure RAG through character/server config instead.