# EasyLink Fin-Chat Financial Research Q&A

## Overview

Fin-Chat is a knowledge Q&A model focused on financial research, built on a large corpus of financial documents. It supports professional queries such as company earnings analysis, industry research, and stock price trends. Responses include citations to original documents (file name, page number, access link) for easy source verification.

The interface uses OpenAI Chat Completions compatible format and supports both streaming and non-streaming response modes. You can integrate it directly using the OpenAI SDK.

For more details, see the [EasyLink official documentation](https://docs.easylink-ai.com/docs/capabilities/qa/api).

**Request URL**: `https://api-us-ca.umodelverse.ai/v1/chat/completions`

## Supported Models

- `easydoc-fin-chat`

## Request Parameters

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| model | string | Yes | Model name, fixed as `easydoc-fin-chat` |
| messages | array | Yes | Conversation message array; supports `user` / `assistant` / `system` |
| stream | boolean | No | Whether to enable streaming response; default `false` |
| temperature | float | No | Temperature parameter, range 0–2, default 1 |
| max_tokens | integer | No | Maximum number of tokens to generate |

## Response Fields

### Non-Streaming Response

| Field | Type | Description |
| :--- | :--- | :--- |
| choices[0].message.content | string | Generated answer text |
| choices[0].message.annotations | array | Document citation list, see below |
| choices[0].finish_reason | string | Completion reason: `stop` / `length` |
| usage.prompt_tokens | integer | Input token count |
| usage.completion_tokens | integer | Output token count |
| usage.total_tokens | integer | Total token count |

### Streaming Response (SSE)

Each message starts with `data: `, and the stream ends with `data: [DONE]`. The `delta` object fields are the same as the non-streaming `message`.

### annotations Document Citations

| Field | Type | Description |
| :--- | :--- | :--- |
| file_name | string | Source document file name |
| url | string | Document access link (signed, time-limited) |
| page_number | integer | Cited page number |

## Examples

### Curl Examples

**Non-streaming:**

```bash
curl -X POST https://api-us-ca.umodelverse.ai/v1/chat/completions \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "easydoc-fin-chat",
    "messages": [
      {"role": "user", "content": "What was BYD Q3 2024 revenue YoY growth rate?"}
    ]
  }'
```

**Streaming:**

```bash
curl -X POST https://api-us-ca.umodelverse.ai/v1/chat/completions \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "easydoc-fin-chat",
    "messages": [
      {"role": "user", "content": "What was BYD Q3 2024 revenue YoY growth rate?"}
    ],
    "stream": true
  }'
```

### Python Example

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api-us-ca.umodelverse.ai/v1",
)

# Streaming call
response = client.chat.completions.create(
    model="easydoc-fin-chat",
    messages=[
        {"role": "user", "content": "What was BYD Q3 2024 revenue YoY growth rate?"}
    ],
    stream=True,
)

for chunk in response:
    delta = chunk.choices[0].delta

    # Process text content
    if delta.content:
        print(delta.content, end="", flush=True)

    # Process document citations (custom extension field)
    if hasattr(delta, "annotations") and delta.annotations:
        for annotation in delta.annotations:
            print(f"\nCitation: {annotation['file_name']} page {annotation['page_number']}")
            print(f"Link: {annotation['url']}")
```

## Response Examples

**Non-streaming response:**

```json
{
  "id": "resp_xxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "easydoc-fin-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "According to BYD's Q3 2024 earnings report, revenue was CNY 201.125 billion, a YoY increase of 24.04%.",
        "annotations": [
          {
            "file_name": "BYD: 2024 Third Quarter Report.pdf",
            "url": "https://oss.easylink-ai.com/easylink-investplatform/file_md5/xxx.pdf?signature=...",
            "page_number": 2
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 64,
    "total_tokens": 192
  }
}
```

## Usage Notes

1. **OpenAI SDK compatible**: Set `base_url` to `https://api-us-ca.umodelverse.ai/v1` and `api_key` to your Modelverse API Key to use the OpenAI SDK directly.
2. **Document citations**: `annotations` is an extension field. When parsing with the standard OpenAI SDK, check with `hasattr` before accessing it.
3. **Citation link expiry**: `annotations[].url` contains signature parameters with an expiry limit. Access it promptly and do not store it for long-term use.
4. **Streaming tip**: When testing streaming responses with cURL, add the `--no-buffer` flag, otherwise output may be delayed.
5. **Billing**: Billed by token count; usage is returned via `usage.prompt_tokens` and `usage.completion_tokens`.