# Model API


This page describes how to access the Genesis **model inference API**, its endpoints, and the request parameters and response fields for each endpoint. The API follows OpenAI-compatible conventions. For key creation, console code generation, and viewing usage, see [Guide · Genesis](../../guides/genesis/index.md).

For errors and rate limits, see [Error Codes](../general/error-codes.md). For built-in system models, see [System Model Library](../general/system-models.md).

Refer to the access information on the Genesis console's **Use** page and actual API responses for paths, field names, and default values. Some endpoints, such as reranking, document recognition, and video generation, have no unified standard in the OpenAI protocol; refer to the live service for implementation details.

## Access Information

### Base URL

Obtain the **Base URL** from the **Use** page in the Genesis console. Example format (refer to the console for the actual domain and path segments):

```text
https://moi.matrixorigin.cn/taas/v1
```

**Path construction**

| Rule | Description |
| --- | --- |
| Version segment | The Base URL usually already includes `/v1` |
| Request URL | `Base URL` + the **Path** column in the table below (for example, `/chat/completions`) |
| Important | Do not append `/v1` again to a Base URL that already includes it, as this would duplicate the version segment |

All paths in the tables below are relative to a Base URL that already includes the version segment.

### Authentication

Use the same request-header authentication as OpenAI:

```http
Authorization: Bearer <API_KEY>
```

- When using the official OpenAI SDK, set `api_key` to the Genesis API Key and `base_url` to the Base URL above.
- Create API Keys in Genesis key management. A key can be bound to available models, rate limits, and quotas. Do not commit keys to a code repository.

### Protocol Compatibility

| Item | Description |
| --- | --- |
| Request fields | Fields such as `model`, `messages`, `temperature`, and `stream` retain their OpenAI semantics |
| Response structure | Structures such as `choices`, `usage`, and `data` follow common OpenAI conventions |
| SDK | Use the official `openai` SDK (Python, Node.js, and others) by overriding `base_url` and `api_key` |

## Endpoint Overview

| Endpoint | Method | Path | Description | Billing Unit |
| --- | --- | --- | --- | --- |
| Chat completions | POST | `/chat/completions` | Text conversations and generation; supports multimodal messages (image input) | Tokens (including image token equivalents) |
| Text embeddings | POST | `/embeddings` | Convert text to vectors | Tokens |
| Document reranking | POST | `/rerank` | Rank candidate documents by relevance | Tokens |
| Document recognition | POST | `/ocr` | Page-based document/image recognition | Pages |
| Image generation | POST | `/images/generations` | Generate images from text | Images |
| Video generation | POST | `/videos/generations` | Generate videos from text or images | Seconds |
| Speech synthesis | POST | `/audio/speech` | Convert text to speech | Characters |
| Speech recognition | POST | `/audio/transcriptions` | Convert speech to text | Duration (minutes) |
| Model list | GET | `/models` | List the models available to the current key | — |

Notes:

- For visual understanding and image-based conversations, prefer multimodal messages with **Chat Completions**. Use **Document Recognition** for traditional page-based OCR.
- For the range of endpoints currently covered by the console code generator, as well as extended endpoints such as Responses and Messages, see [Integrate with the Genesis API](../../guides/genesis/integrate.md). This page is primarily a parameter quick reference.

---

## Chat Completions

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/chat/completions` |

### Request Parameters

| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `model` | string | Model ID, available from the model list or Model Marketplace | — |
| `messages` | array | Message list. Each message contains `role` (`system` / `user` / `assistant`) and `content` (text or a multimedia array) | — |
| `temperature` | number | Sampling temperature, approximately 0–2 | 0.7 |
| `max_tokens` | integer | Maximum number of tokens to generate | Model default |
| `stream` | boolean | Whether to stream the response using SSE | false |
| `top_p` | number | Nucleus sampling, in the range 0–1 | 0.9 |
| `frequency_penalty` | number | Frequency penalty, approximately −2–2 | 0 |
| `presence_penalty` | number | Presence penalty, approximately −2–2 | 0 |
| `seed` | integer | Random seed; fixing it makes the output reproducible for the same input | Random |

### Response Fields

| Field | Description |
| --- | --- |
| `choices[0].message.content` | Model response body |
| `choices[0].finish_reason` | `stop` indicates normal completion; `length` indicates that `max_tokens` was reached |
| `usage.prompt_tokens` | Input tokens |
| `usage.completion_tokens` | Output tokens |
| `usage.total_tokens` | Total tokens, used for billing reconciliation |

When `stream` is `true`, the response consists of multiple `data:` events. Incremental content is located at `choices[0].delta.content`, and the termination marker is `data: [DONE]`.

### Multimodal Messages

In the same endpoint, set a `user` message's `content` to an array to combine text and images:

```json
[
  {"type": "text", "text": "Describe this image"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
]
```

`image_url.url` supports a public URL or the `data:image/jpeg;base64,...` format. `prompt_tokens` may include image tokens calculated based on image resolution.

### Request Example

```http
POST {Base URL}/chat/completions
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

```json
{
  "model": "<model_id>",
  "messages": [
    {"role": "system", "content": "You are a rigorous data assistant."},
    {"role": "user", "content": "Explain what data lineage is."}
  ],
  "temperature": 0.7,
  "stream": false
}
```

---

## Text Embeddings

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/embeddings` |

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Embedding model ID |
| `input` | string or array | A single text string or an array of text strings |

### Response Fields

| Field | Description |
| --- | --- |
| `data[].embedding` | Vector; its dimensions are determined by the model |
| `data[].index` | Index corresponding to the batched input |
| `usage.total_tokens` | Billable usage |

---

## Document Reranking

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/rerank` |

This endpoint has no unified standard definition in the OpenAI protocol. Refer to the actual API for field names and paths.

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Reranking model ID |
| `query` | string | Query text |
| `documents` | array | List of candidate document strings |
| `top_n` | integer | Return the top N entries; all entries may be returned if omitted |
| `return_documents` | boolean | Whether to return the original text in the results; defaults to true |

### Response Fields

| Field | Description |
| --- | --- |
| `results[]` | Results ordered by descending relevance |
| `results[].index` | Index corresponding to `documents` in the request |
| `results[].relevance_score` | Relevance score, commonly in the range 0–1 |
| `results[].document.text` | Original text (when `return_documents` is true) |
| `usage.total_tokens` | Billable usage (if returned) |

---

## Document Recognition

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/ocr` |

This endpoint recognizes text in document pages or images. For visual conversation use cases, prefer the multimodal messages provided by [Chat Completions](#chat-completions).

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Document recognition model ID |
| `image_url` / `image_base64` | string | Resource to recognize; refer to the API for the exact field name |
| `format` | string | Output format, such as `text`, `json` (including coordinates), or `markdown`; defaults to `text` |

### Response Fields

| Field | Description |
| --- | --- |
| `text` | Full recognized text |
| `blocks[]` | Block-level results when `format` is `json` (such as coordinates and confidence) |
| `usage.pages` | Number of billable pages |

---

## Image Generation

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/images/generations` |

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Image generation model ID |
| `prompt` | string | Text prompt |
| `size` | string | Output dimensions, such as `512x512`, `1024x1024`, `1280x720`, or `1536x1024` |
| `n` | integer | Number of images to generate, commonly 1–4; defaults to 1 |
| `negative_prompt` | string | Negative prompt (if supported by the model) |
| `seed` | integer | Random seed (if supported by the model) |

### Response Fields

| Field | Description |
| --- | --- |
| `data[].url` | Generated image URL; it may expire, so copy the image to persistent storage promptly |
| `usage.images` | Number of billable images |

---

## Video Generation

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/videos/generations` |

This endpoint usually uses an asynchronous task model. After submission, poll for the result or receive it through a callback. Refer to the actual API for its conventions.

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Video generation model ID |
| `prompt` | string | Text prompt |
| `image_url` | string | Source image URL for image-to-video generation (if supported) |
| `duration` | integer | Duration in seconds, such as 5, 10, or 15 |
| `resolution` | string | Resolution, such as `720p` or `1080p` |

### Response Fields

| Field | Description |
| --- | --- |
| `id` | Task identifier |
| `status` | Task status, such as `queued`, `processing`, `succeeded`, or `failed` |
| `video_url` | Video URL after successful completion |
| `usage.seconds` | Number of billable seconds |

---

## Speech Synthesis

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/audio/speech` |

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Speech synthesis model ID |
| `input` | string | Text to synthesize |
| `voice` | string | Voice identifier |
| `format` | string | Audio format, such as `mp3`, `wav`, or `opus` |
| `speed` | number | Speech rate, commonly in the range 0.5–2.0; defaults to 1.0 |

### Response

| Item | Description |
| --- | --- |
| Response body | Usually a binary audio stream rather than JSON; `Content-Type` varies with `format` |
| Response headers | May include a request identifier and fields related to billable characters; refer to the actual API |

---

## Speech Recognition

| Item | Value |
| --- | --- |
| Method | POST |
| Path | `/audio/transcriptions` |

### Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `model` | string | Speech recognition model ID |
| `file` | file | Audio file (multipart); common formats include mp3, wav, and m4a |
| `language` | string | Language, such as `zh`, `en`, or `auto` |
| `response_format` | string | Output format, such as `text`, `srt`, or `json` |
| `timestamp` | boolean | Whether to return more granular timestamps (if supported) |

### Response Fields

| Field | Description |
| --- | --- |
| `text` | Full transcription |
| `language` | Recognized language |
| `duration` | Audio duration in seconds, used for per-minute billing |
| `segments[]` | Segment information when `response_format` is `json` |

---

## Model List

| Item | Value |
| --- | --- |
| Method | GET |
| Path | `/models` |

No request body is required. The request must include valid authentication.

### Response Fields

| Field | Description |
| --- | --- |
| `data[].id` | Model ID; use it as the `model` value when calling other endpoints |
| `data[].type` | Model type |
| `data[].status` | Availability status, such as `normal`, `degraded`, or `error` |

For model selection guidance, see [System Model Library](../general/system-models.md).

---

## Result Fields and Billable Usage

When implementing a client, prioritize reading:

| Purpose | Common Location |
| --- | --- |
| Application result | `message.content`, `embedding`, `url`, `text`, `results`, audio streams, and so on |
| Usage for this request | The `usage` object, or an endpoint-specific response header |

| Endpoint | Billing Unit |
| --- | --- |
| Chat completions, text embeddings, and document reranking | Tokens |
| Document recognition | Pages |
| Image generation | Images |
| Video generation | Seconds |
| Speech synthesis | Characters |
| Speech recognition | Duration (minutes) |

For unit prices and Credit rules, see [Costs and Billing](../../guides/billing/index.md) and the Genesis pricing information.