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.

For errors and rate limits, see Error Codes. For built-in system models, see System Model Library.

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):

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:

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. 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:

[
  {"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¶

POST {Base URL}/chat/completions
Authorization: Bearer <API_KEY>
Content-Type: application/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.

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.

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 and the Genesis pricing information.

Model API¶

Access Information¶

Base URL¶

Authentication¶

Protocol Compatibility¶

Endpoint Overview¶

Chat Completions¶

Request Parameters¶

Response Fields¶

Multimodal Messages¶

Request Example¶

Text Embeddings¶

Request Parameters¶

Response Fields¶

Document Reranking¶

Request Parameters¶

Response Fields¶

Document Recognition¶

Request Parameters¶

Response Fields¶

Image Generation¶

Request Parameters¶

Response Fields¶

Video Generation¶

Request Parameters¶

Response Fields¶

Speech Synthesis¶

Request Parameters¶

Response¶

Speech Recognition¶

Request Parameters¶

Response Fields¶

Model List¶

Response Fields¶

Result Fields and Billable Usage¶

Related Documentation¶