Prepare to call an API¶
Every endpoint page assumes your request already has four things ready: the service address, a credential, a workspace (AI Studio only), and the resource IDs in the path. This page shows where each comes from and where it goes in the request.
Service addresses¶
API |
Service prefix |
What it calls |
|---|---|---|
Genesis |
|
Model chat, embeddings, reranking |
AI Studio |
|
Resources and tasks inside a workspace |
The prefix is only the beginning; each endpoint adds its own path. Every endpoint page prints the full URL and method at the top—for example, POST https://token.moi.matrixorigin.cn/v1/chat/completions on Create a Chat Completion—copy it directly instead of assembling paths from the prefix yourself.
Credentials¶
Both kinds of credentials are issued on the Access credentials page in the console, but they go into different places in the request:
Genesis: in
Authorization: Bearer <credential>. Personal access tokens and service-account API keys both work; for creation steps, see Manage API Keys.AI Studio: in
X-API-Key: <personal access token>. Some actions also require anX-Workspace-IDheader; the next section shows how to get a workspace ID.
Use one authentication method per request: if you send X-API-Key, don’t also send Authorization or Cookie. Keep tokens out of URLs, logs, code repositories, and screenshots.
Workspace and resource IDs¶
AI Studio endpoints are organized around workspaces. Call List workspaces first, find the target workspace’s id in data.workspaces in the response, and pass it in the X-Workspace-ID header of later requests.
Placeholders like {invitation_id} in endpoint URLs accept IDs, not names. Every ID comes from the response of a corresponding endpoint: workspace IDs from List workspaces, task IDs from the response of the endpoint that created the task, and so on for every other resource.
Reading responses¶
Successful responses: the “Successful response” section of each endpoint page lists every returned field. Resource IDs, task IDs, file locations, and pagination cursors needed by later requests all come from this section.
Asynchronous tasks: a successful response from a create or run endpoint only means the task was accepted, not completed. Save the task ID and confirm the result through the query endpoint given on the endpoint page.
Error responses: error structures are documented in the “Error response” section of each endpoint page and are not shared between the two APIs—don’t apply error codes across endpoints.
Downloads and streaming: for endpoints marked as file downloads or streaming output, save the file or read events incrementally as the endpoint page describes; don’t parse them as ordinary JSON.