API catalog

This page lists the public model-calling HTTP APIs (mgk_ API Key, gateway https://api.modelgo.ai).

Before you call

Create an API key (mgk_) at https://console.modelgo.ai. The full secret is shown once.
export MODELGO_API_KEY="your-key".
Call GET /v1/models for logical model names.
A model only accepts endpoints listed in its public_protocols. Hitting any other path returns HTTP 400, error_class=model_protocol_not_offered (app_error_id=4005).

Auth

http

Authorization: Bearer $MODELGO_API_KEY

Anthropic clients may send x-api-key; Gemini clients may send x-goog-api-key. Priority: Authorization > x-api-key > x-goog-api-key. See Authentication.

Missing or invalid key (HTTP 401):

json

{
  "error": {
    "code": 401,
    "message": "unauthorized",
    "metadata": {
      "app_error_id": 4011,
      "error_class": "auth",
      "request_id": "gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b"
    }
  },
  "trace_id": "bbaf7b379c1dbb4b42adbabf65f5f530"
}

Keep X-Request-ID, X-Trace-ID, and body trace_id.

Protocol matching

Model	Endpoint	Result
`qwen3.6-flash`	`POST /v1/chat/completions`, `POST /v1/responses`	200
`qwen3.6-flash`	`POST /v1/completions`	400 `model_protocol_not_offered`
`claude-fable-5`	`POST /v1/messages`	200
`text-embedding-3-small`	`POST /v1/embeddings`	200
`speech-2.8-turbo`	`POST /v1/audio/speech`	400 `model_protocol_not_offered`
`speech-2.8-turbo`	`POST /minimax/v1/t2a_v2`	200
`doubao-seedance-2.0-mini`	`POST /v1/video/generations`	400 `model_protocol_not_offered`
`doubao-seedance-2.0-mini`	`POST /v1/content_generation/tasks`, `POST /ark/api/v3/contents/generations/tasks`	200
`doubao-seedream-5.0-lite`	`POST /v1/images/generations` with `size` ≥ ~1920×1920	200

Catalog

Public means the gateway mounts the route. Whether a given model accepts it still depends on public_protocols and the key's policy.

Text and model list

Method	Path	Status	Notes
`GET`	`/v1/models`	Public	Logical models allowed for this key
`POST`	`/v1/responses`	Public	OpenAI Responses (preferred)
`POST`	`/v1/chat/completions`	Public	OpenAI Chat Completions
`POST`	`/v1/completions`	Public	Legacy; most chat models do not offer it
`POST`	`/v1/messages`	Public	Anthropic Messages

Vectors / images / audio / rerank

Method	Path	Status	Notes
`POST`	`/v1/embeddings`	Public	Text embeddings
`POST`	`/v1/embeddings/multimodal`	Public	Needs a multimodal-embedding protocol
`POST`	`/v1/images/generations`	Public	Image generation
`POST`	`/v1/images/edits`	Public	Multipart image edits
`POST`	`/v1/audio/speech`	Public	OpenAI TTS; not every speech model offers it
`POST`	`/minimax/v1/t2a_v2`	Public	MiniMax native TTS; see MiniMax audio inbound
`POST`	`/v1/audio/transcriptions`	Public	Multipart STT
`POST`	`/v1/audio/translations`	Public	Multipart translation
`POST`	`/v1/rerank`	Public	Rerank
`POST`	`/v1/reranks`	Public / alias	Same as `/v1/rerank`

Managed async video

Method	Path	Status	Notes
`POST`/`GET`/`DELETE`	`/v1/content_generation/tasks` and `.../{task_id}`	Public	Generic async tasks
`POST`/`GET`/`DELETE`	`/ark/api/v3/contents/generations/tasks` and `.../{task_id}`	Public	Same pipeline, Ark spelling
`POST`/`GET`/`DELETE`	`/minimax/v2/video_generation` and `.../{task_id}`	Public	MiniMax video V2; pricing dimensions required
`POST`/`GET`/`DELETE`	`/v1/video/generations`, `/v1/videos/{task_id}`, `/v1/videos/{task_id}/content`	Public	OpenAI-compatible video; model must offer it

Cancel (DELETE) may return provider_unsupported if the upstream has no cancel API.

Verified calls

List models:

bash

curl https://api.modelgo.ai/v1/models \
  -H "Authorization: Bearer $MODELGO_API_KEY"

Chat Completions:

bash

curl https://api.modelgo.ai/v1/chat/completions \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.6-flash","messages":[{"role":"user","content":"ping"}],"max_tokens":64}'

Empty {} → HTTP 400 client_invalid. Unknown model → HTTP 403 policy / model_not_in_catalog.

Responses: POST /v1/responses with input + max_output_tokens. Messages: POST /v1/messages with x-api-key and max_tokens. The Messages response model field may be an upstream id, not the logical name.

Embeddings: text-embedding-3-small returned 1536-d vectors.

Images: doubao-seedream-5.0-lite rejects 1024x1024 (provider_invalid, min 3686400 pixels). 2048x2048 succeeded.

Speech: use MiniMax audio inbound for speech-2.8-*.

Video: Seedance uses /v1/content_generation/tasks (create returns {"id","model","status":"queued"}; poll later returns status=succeeded, plus resolution / ratio / duration). /v1/video/generations is model_protocol_not_offered for doubao-seedance-2.0-mini.

Streaming

Set stream: true. OpenAI-shaped endpoints use text/event-stream frames data: {json} ending with data: [DONE]. /v1/messages keeps native Anthropic event: frames. A chunk with error is a failure even if HTTP status was 200.

Limits

Rate limits: HTTP 429 (quota or provider_rate_limit); honor Retry-After.
No client idempotency key on sync calls. Each async POST creates a new task; poll by returned id.
No pagination on this surface; GET /v1/models returns the full list for the key.
Request body limit: 10 MiB (10,485,760 bytes) per request. A larger body returns HTTP 400 with error_class client_invalid, and the message states the limit. A request that declares its Content-Length is refused as soon as the header shows it is over the limit, without uploading the rest. Base64-inlined images grow by about 4/3, so keep one raw image under about 7.5 MiB.

See Errors, Text generation, MiniMax audio inbound, Async tasks.