Response Format

The Arvae AI API returns responses in a consistent JSON format across all models. This page documents the structure of API responses and how to parse them.

Example Responses

Here are typical responses from the API endpoints:

V1 Endpoint Response Example

1{
2    "id": "arvae-1745773067-1VSEv2b7Nzk8wAZfMJst",
3    "model": "openai/chatgpt-4o-latest",
4    "choices": [
5        {
6            "finish_reason": "stop",
7            "index": 0,
8            "message": {
9                "role": "assistant",
10                "content": "Hello! I'm here and ready to help. How are you?"
11            }
12        }
13    ],
14    "token_metrics": {
15        "input_tokens": 12,
16        "output_tokens": 14,
17        "total_tokens": 26
18    }
19}

V2 Endpoint Response Example

1{
2    "model": "hanooman/hanooman-everest",
3    "id": "arvae-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}

Response Fields

The API response includes the following fields:

Field	Description
id	Unique identifier for the completion
object	Always "chat.completion"
created	Unix timestamp for when the completion was created
model	Model used for the completion
choices	Array of completion choices (typically just one)
choices[].message	The message object with role and content
choices[].finish_reason	Reason why the completion finished (e.g., "stop", "length")
token_metrics	Token usage information for billing and tracking
conversation_id	Optional field in V2 API for tracking conversation context

Handling Responses

Accessing Response Content

The most common use case is to extract the text content from the response. The content is located in choices[0].message.content:

// JavaScript example const responseContent = response.choices[0].message.content; // Python example response_content = response["choices"][0]["message"]["content"]

Finish Reasons

The finish_reason field indicates why the model stopped generating text:

stop: The model reached a natural stopping point or a specified stop sequence
length: The response exceeded the max_tokens parameter
content_filter: Content was omitted due to safety filters
function_call: The model decided to call a function (for models that support function calling)

You can use this field to determine if the response was truncated and potentially request more tokens if needed.

Token Metrics Information

The token_metrics object contains token count information, which is useful for tracking API usage and costs:

input_tokens: Number of tokens in the input (including system and user messages)
output_tokens: Number of tokens in the generated response
total_tokens: Total tokens used (input_tokens + output_tokens)

This information can be used to track API usage and estimate costs based on the pricing of the specific model.

Streaming Responses

When using streaming mode (stream: true), the response format is different. Instead of receiving a single response object, you'll receive a stream of data chunks.

Each chunk contains a partial delta of the response, which you'll need to accumulate to build the complete response.

Using Streaming

For detailed examples of how to handle streaming responses, see our Streaming Responses Guide.

Error Handling

In case of an error, the API will return an error object with details about what went wrong. It's important to implement proper error handling in your applications.

Example Error Response

1{
2  "error": {
3    "message": "The model 'nonexistent-model' does not exist or you don't have access to it",
4    "type": "invalid_request_error",
5    "param": "model",
6    "code": "model_not_found"
7  }
8}

View Error Handling Guide →Request Parameters