Output Formats

Understanding the response structure from Rustellar AI models.

Response Structure

All API responses follow a consistent JSON format.

Standard Response

{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "helix-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  }
}

Response Fields

Top-level Fields

Field	Type	Description
id	string	Unique identifier for the completion
object	string	Always "chat.completion"
created	integer	Unix timestamp of creation time
model	string	The model used for generation
choices	array	Array of completion choices (usually 1)
usage	object	Token usage information

Choice Object

Field	Type	Description
index	integer	Index of the choice (starts at 0)
message	object	The generated message
finish_reason	string	Reason for completion ending

Message Object

Field	Type	Description
role	string	Always "assistant" for responses
content	string	The actual generated text

Usage Object

Field	Type	Description
prompt_tokens	integer	Number of tokens in the prompt
completion_tokens	integer	Number of tokens in the completion
total_tokens	integer	Total tokens used (prompt + completion)

Finish Reasons

The finish_reason field indicates why the generation stopped:

Reason	Description
stop	Natural stopping point reached
length	Max tokens limit reached
content_filter	Content filtered due to policy
null	Still generating (streaming mode)

Streaming Responses

For real-time output, use streaming mode.

Enabling Streaming

import requests

# ストリーミングモードを有効化
response = requests.post(
    "https://api.rustellar.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "helix-v1",
        "messages": [
            {"role": "user", "content": "Tell me a story"}
        ],
        "stream": True  # ストリーミングを有効化
    },
    stream=True  # requests.postでストリーミングレスポンスを受信
)

# ストリーミングデータを逐次処理
for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))

Streaming Response Format

Each chunk follows this format:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"helix-v1","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"helix-v1","choices":[{"index":0,"delta":{"content":" there"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"helix-v1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Processing Streaming Responses

import json

def process_stream(response):
    """ストリーミングレスポンスを処理する関数"""
    for line in response.iter_lines():
        if line:
            # "data: " プレフィックスを除去
            line_text = line.decode('utf-8')
            if line_text.startswith('data: '):
                data = line_text[6:]  # "data: " を削除

                # 終了シグナルをチェック
                if data == '[DONE]':
                    break

                # JSONをパース
                try:
                    chunk = json.loads(data)
                    # デルタコンテンツを取得
                    delta = chunk['choices'][0]['delta']
                    if 'content' in delta:
                        print(delta['content'], end='', flush=True)
                except json.JSONDecodeError:
                    continue

# 使用例
response = requests.post(
    "https://api.rustellar.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "helix-v1",
        "messages": [{"role": "user", "content": "Write a poem"}],
        "stream": True
    },
    stream=True
)

process_stream(response)

Error Responses

When an error occurs, the API returns an error object:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Common Error Codes

Code	Description
invalid_api_key	Invalid or missing API key
rate_limit_exceeded	Too many requests
invalid_request_error	Malformed request
model_not_found	Specified model doesn't exist
context_length_exceeded	Input exceeds model's context window

Error Handling Example

import requests

def make_api_call(messages):
    """エラーハンドリング付きAPI呼び出し"""
    try:
        response = requests.post(
            "https://api.rustellar.com/v1/chat/completions",
            headers={
                "Authorization": "Bearer YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={
                "model": "helix-v1",
                "messages": messages
            }
        )

        # HTTPステータスコードをチェック
        response.raise_for_status()

        # レスポンスをパース
        data = response.json()
        return data['choices'][0]['message']['content']

    except requests.exceptions.HTTPError as e:
        # HTTPエラーを処理
        error_data = e.response.json()
        print(f"API Error: {error_data['error']['message']}")
        return None

    except Exception as e:
        # その他のエラーを処理
        print(f"Error: {str(e)}")
        return None

# 使用例
result = make_api_call([
    {"role": "user", "content": "Hello!"}
])

if result:
    print(result)

Best Practices

1. Always check finish_reason to understand why generation stopped
2. Monitor token usage to control costs
3. Implement error handling for robust applications
4. Use streaming for long responses to improve user experience
5. Parse responses safely with try-catch blocks

Next Steps

• Review Input Formats
• Check Rate Limits
• Explore Models