Text Generation & Prompting

ASI:One’s Chat Completion endpoint lets you turn plain instructions (a prompt) into rich text—code, math, structured JSON, or natural-sounding prose. This page shows how to call the endpoint, explains every request field, and lists common errors.

---

Endpoint

POST https://api.asi1.ai/v1/chat/completions

Required headers

Header	Type	Description
Authorization	string	Bearer YOUR_API_KEY
x-session-id	string	A unique session identifier used for rate-limiting & tracing

---

Request body

Field	Type	Required	Description
agent_address	string	optional	Address of the calling agent (for rate-limits & audit).
model	string	optional	E.g. asi1-mini, asi1-fast, asi1-extended
messages	array<object>	optional	Conversation history (see below)
temperature	number	optional	0-2. Controls randomness. Default 1.0
max_tokens	integer	optional	Max tokens to generate
stream	boolean	optional	If true the response is Server-Sent Events
tools	array<object>	optional	For tool-calling
web_search	boolean	optional	Enable/disable web search

Message objects follow the OpenAI style:

{
  "role": "user | assistant | system",
  "content": "…"
}

---

Quick start (choose your language)

curl

curl -X POST https://api.asi1.ai/v1/chat/completions \
  -H "Authorization: Bearer $ASI_ONE_API_KEY" \
  -H "x-session-id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "asi1-mini",
    "messages": [
      {"role": "user", "content": "Write a one-sentence bedtime story about a unicorn."}
    ]
  }'

Python

import os, requests

url = "https://api.asi1.ai/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.getenv('ASI_ONE_API_KEY')}",
    "x-session-id": "my-session-123",
    "Content-Type": "application/json"
}
json = {
    "model": "asi1-mini",
    "messages": [{"role": "user", "content": "Write a one-sentence bedtime story about a unicorn."}]
}

resp = requests.post(url, headers=headers, json=json)
print(resp.json()["choices"][0]["message"]["content"])

JavaScript

const res = await fetch("https://api.asi1.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ASI_ONE_API_KEY}`,
    "x-session-id": "my-session-123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "asi1-mini",
    messages: [{ role: "user", content: "Write a one-sentence bedtime story about a unicorn." }]
  })
});
const data = await res.json();
console.log(data.choices[0].message.content);

---

Response schema (200)

{
  "id": "id_aJEoW7curd0MBJGJ3",
  "model": "asi1-mini",
  "executable_data": [],
  "intermediate_steps": [],
  "conversation_id": null,
  "thought": ["\n\n"],
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Under a sky dusted with stardust, a gentle unicorn with a shimmering silver mane galloped softly through the dream fields, sprinkling peaceful slumber into the hearts of sleeping creatures with each glowing hoofprint."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 73,
    "completion_tokens": 48,
    "total_tokens": 121
  }
}

Field breakdown

Field	Type	Description
id	string	Unique identifier for the completion.
model	string	Model that generated the response.
choices	array | null	List of generated choices/messages.
executable_data	array | null	Structured tool calls or agent manifests (agentic models).
intermediate_steps	array | null	Internal reasoning breadcrumbs (streaming/extended).
conversation_id	string | null	ID you can supply to continue a thread (optional).
thought	array | null	Lightweight reasoning trace returned during streaming.
usage	object | null	Token-usage accounting.

choices[] object

Field	Type	Description
index	integer	Position in the choices array.
finish_reason	string	Why generation stopped (stop, length, etc.).
message	object | null	Assistant message when not streaming.
delta	object | null	Incremental message chunk when stream=true.

message / delta object

Field	Type	Description
role	string	Always assistant for model output.
content	string	Text produced so far (streaming) or full text (non-stream).

usage object

Field	Type	Description
prompt_tokens	integer	Number of tokens you sent.
completion_tokens	integer	Tokens generated by the model.
total_tokens	integer	Sum of prompt + completion (used for billing/limits).

---

Error codes

Code	Meaning
400	Bad request (invalid JSON, missing fields)
404	Not found (unknown endpoint)
429	Rate limit exceeded
500	Internal server error

---

Choosing a model

• asi1-mini – fastest & cheapest, great for prototypes.
• asi1-fast – balanced speed and quality.
• asi1-extended – larger context window.
• asi1-agentic – excels at multi-step reasoning.
• asi1-graph – tuned for analytical & graph tasks.

When in doubt start with asi1-fast and adjust based on speed/cost needs.

---

Prompt engineering basics

1. Use roles – system for global instructions, user for questions.
2. Be explicit – tell the model what format you expect.
3. Few-shot examples – include 2-3 Q&A pairs to steer style.
4. Temperature – lower (0-0.3) for deterministic, higher for creativity.
5. Pin versions – specify model snapshot once versioning is exposed.