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
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 function 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",
    "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",
    "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

import OpenAI from 'openai';
const apiKey = process.env.ASI_ONE_API_KEY;
const client = new OpenAI({
  apiKey: apiKey,
  baseURL: 'https://api.asi1.ai/v1',
});
const response = await client.chat.completions.create({
  model: 'asi1',
  messages: [
    { role: 'user', content: 'Write a one-sentence bedtime story about a unicorn.' }
  ],
  extra_headers: {
    'x-session-id': 'my-session-123'
  }
});
console.log(response.choices[0].message.content);

---

Response schema (200)

{
    "id": "083bd6ca857843c0911edf83799ca6c8",
    "choices": [{
        "finish_reason": "stop",
        "index": 0,
        "logprobs": null,
        "message": {
            "content": "A little unicorn with a silver mane pranced through clouds of cotton candy, then curled up in a meadow of starlight to sleep while her horn glowed softly like a night-light.",
            "refusal": null,
            "role": "assistant",
            "annotations": null,
            "audio": null,
            "function_call": null,
            "tool_calls": null,
            "reasoning_content": null
        },
        "matched_stop": 151336
    }],
    "created": 1768476062,
    "model": "asi1",
    "object": "chat.completion",
    "service_tier": null,
    "system_fingerprint": null,
    "usage": {
        "completion_tokens": 39,
        "prompt_tokens": 2107,
        "total_tokens": 2146,
        "completion_tokens_details": null,
        "prompt_tokens_details": null,
        "reasoning_tokens": 0
    },
    "metadata": {
        "weight_version": "default"
    }
}

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

---

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.