.svg){kind=small}
API Response Format
Understanding the structure and format of responses from the UltraSafe AI API.
Response Structure
All successful API responses follow a consistent structure. Here are the key fields you can expect:
| Field | Description |
|---|---|
| id | Unique identifier for the request |
| model | The model used for the completion |
| conversation_id | Optional field for tracking conversation context |
| choices | Array of completion choices (usually contains one item) |
| token_metrics | Detailed breakdown of token usage for the request |
Example Response
Here is a typical response from the API:
1{
2 "model": "ultrasafe/usf-mini",
3 "id": "ultrasafe-id_yNwd8EyBzJJO1W2nV",
4 "conversation_id": null,
5 "choices": [
6 {
7 "index": 0,
8 "finish_reason": "stop",
9 "message": {
10 "role": "assistant",
11 "content": "Hello! I'm functioning optimally today, thank you for asking. How can I assist you?"
12 }
13 }
14 ],
15 "token_metrics": {
16 "input_tokens": 125,
17 "output_tokens": 21,
18 "total_tokens": 146
19 }
20}Token Metrics
The token_metrics field provides detailed information about token usage:
| Field | Description |
|---|---|
| input_tokens | Number of tokens in the input (prompt + messages) |
| output_tokens | Number of tokens in the generated response |
| total_tokens | Sum of input and output tokens |
Choices Array
The choices array contains the generated completions. Each choice object includes:
| Field | Description |
|---|---|
| index | The index of the choice (usually 0 for single completions) |
| message | The generated message object with role and content |
| finish_reason | Reason why the generation stopped (e.g., “stop”, “length”) |
Error Responses
When an error occurs, the API returns an error response with the following structure:
1{
2 "error": {
3 "message": "Invalid API key provided",
4 "type": "auth_error",
5 "param": null,
6 "code": "invalid_api_key"
7 }
8}For more details about error handling, see our Error Handling Guide.