ms-hub

# ModelScope Unified Operations Entrypoint > Verified with modelscope 1.37.1, Python 3.12 (2026-06-23) Operate the full range of ModelScope platform capabilities through OpenAPI, CLI, and SDK, covering Hub (models/datasets), Studio, MCP services, and the Skills Center (Skills). This Skill serves as a quick-reference entrypoint; complex operational workflows require the dedicated Skill. ## Requirements ```bash pip install modelscope ``` `pip install modelscope` installs both the SDK (`modelscope.hub.api.HubApi`) and two sets of command-line entrypoints: - **`ms` (driven by modelscope_hub v0.1.2)**: Hub / Studio / MCP operations (`download`/`upload`/`create`/`deploy`/`mcp`/`secret`/…). This document uses `ms` uniformly for Hub/Studio/MCP commands. - **`modelscope` (legacy CLI)**: additionally provides commands such as `skills` (`modelscope skills add`) — `ms` (modelscope_hub) **does not have** a `skills` subcommand. > ⚠️ Both packages register the `ms` and `modelscope` entrypoints; which one actually takes effect depends on install order. If an entrypoint lacks a required subcommand (typically: `ms` has no `skills`), switch to the other entrypoint, or use the SDK / `curl install.sh` (see §9 and `references/skills-center.md`). ## Authentication All operations rely on unified authentication: ```bash # Environment variable export MODELSCOPE_API_KEY="your_token" # Token retrieval URL # $MODELSCOPE_ENDPOINT/my/myaccesstoken ``` | Operation method | Authentication method | |----------|----------| | OpenAPI | `Authorization: Bearer $MODELSCOPE_API_KEY` | | CLI | `ms login --token $MODELSCOPE_API_KEY` | | SDK | `api.login(access_token=os.environ['MODELSCOPE_API_KEY'])` | ## Site selection & endpoint routing ModelScope runs two independent sites — the **domestic** site `https://modelscope.cn` (default) and the **international** site `https://www.modelscope.ai`. They have separate accounts, access tokens, and content catalogs. Every operation here targets whichever site `$MODELSCOPE_ENDPOINT` points to. ### Pick the target site (intent analysis) 1. **Respect an existing setting** — if `MODELSCOPE_ENDPOINT` is already exported, use it as-is. 2. **Explicit intent** — "international" / "modelscope.ai" / "overseas" ⇒ international; "domestic" / "modelscope.cn" ⇒ domestic. 3. **Match the token or URL the user provides** — a `modelscope.ai` token or link ⇒ international (and vice versa). 4. **Default to the domestic site** (`https://modelscope.cn`) when there is no signal; ask the user if the task clearly targets one audience but the site is ambiguous. ### Configure ```bash # Export the endpoint first — the examples below reference $MODELSCOPE_ENDPOINT: export MODELSCOPE_ENDPOINT="https://modelscope.cn" # domestic (default) # export MODELSCOPE_ENDPOINT="https://www.modelscope.ai" # international export MODELSCOPE_API_KEY="<token issued by THAT site>" # tokens are site-scoped — must match the site ``` One `MODELSCOPE_ENDPOINT` reroutes everything derived from it: the OpenAPI base (`$MODELSCOPE_ENDPOINT/openapi/v1`), the `ms` CLI, the `modelscope_hub` SDK, and git push URLs (`$MODELSCOPE_ENDPOINT/{models,datasets,studios}/…`). Resolution precedence (modelscope_hub): explicit arg > `MODELSCOPE_ENDPOINT` > `MODELSCOPE_DOMAIN` (deprecated) > default `https://modelscope.cn`. For public reads you may also set `MODELSCOPE_PREFER_AI_SITE=true` to try `.ai` before `.cn`. > **Tokens are site-scoped** (stored per endpoint host): a `modelscope.cn` token will not authorize write/private operations on `modelscope.ai`. Get each site's token from `$MODELSCOPE_ENDPOINT/my/myaccesstoken`. > > All examples below use `$MODELSCOPE_ENDPOINT/openapi/v1` as the base — **export `MODELSCOPE_ENDPOINT` first** (raw `curl` needs it set; the `ms` CLI and SDK additionally fall back to `https://modelscope.cn` when it is unset). A few marketplace/doc links (skills `install.sh`, `/docs/…`) show the domestic host — swap to your site's host when targeting international. ## Conventions | Item | Value | |------|-----| | **OpenAPI Base URL** | `$MODELSCOPE_ENDPOINT/openapi/v1` (default `https://modelscope.cn`) | | **Success response** | `{"success": true, "data": {...}, "request_id": "..."}` | | **Error response** | `{"success": false, "code": "ERROR_CODE", "message": "..."}` | | **HTTP status codes** | `200` success / `401` unauthorized / `404` not found / `500` server error | | **Default branch** | `master` (not main) | | **Pagination limit** | `page_number × page_size ≤ 3000` | ## Quick Decision Guide ``` User wants to... │ ├─── Hub: models/datasets ───────────────────────────── │ ├── Search models/datasets → OpenAPI GET /models or /datasets │ ├── View details → GET /models/{owner}/{repo} or SDK model_info() │ ├── Download → CLI: ms download owner/repo │ ├── Upload → CLI: ms upload owner/repo ./local │ ├── Create repository → CLI: ms create owner/repo │ ├── Browse files → SDK: api.get_model_files() │ ├── Inspect dataset → uv run scripts/ms_inspect_dataset.py │ └── Version management → SDK: api.get_model_branches_and_tags() │ ├─── Studio ────────────────────────────── │ ├── Create Studio → POST /studios or CLI: ms create owner/repo --repo-type studio │ ├── Deploy/restart → CLI: ms deploy owner/repo --repo-type studio │ ├── View status → GET /studios/{owner}/{repo} │ ├── View logs → CLI: ms logs owner/repo --log-type run │ ├── Stop → CLI: ms stop owner/repo --repo-type studio │ ├── Update settings → CLI: ms settings owner/repo key=value --repo-type studio │ ├── Available configs → GET /studios/hardware, /studios/sdk-versions, /studios/base-images │ ├── Plaintext variables → GET/POST/PUT/DELETE /studios/{owner}/{repo}/variables │ ├── Secrets → GET/POST/PUT/DELETE /studios/{owner}/{repo}/secrets (or ms secret ...) │ └── Full deployment workflow → see ms-studio-deploy │ ├─── MCP: service management ────────────────────────────── │ ├── Search MCP services → CLI: ms mcp list --search "..." │ ├── View details → CLI: ms mcp info @author/name │ ├── Deploy service → CLI: ms mcp deploy @author/name │ ├── Undeploy service → CLI: ms mcp undeploy @author/name │ ├── My deployed → GET /mcp/servers/operational │ └── IDE configuration / full orchestration → see references/mcp-services.md │ ├─── Skills: Skills Center ──────────────────────────── │ ├── Search skills → GET /skills?search=... │ ├── View details → GET /skills/{id} │ ├── Install skill → modelscope skills add @author/skill-name (legacy CLI; ms has no skills) │ ├── Publish skill → POST /files/upload + POST /skills │ ├── Update skill → PATCH /skills/{owner}/{skill_name}/settings │ └── Category system / packaging spec / full publish → see references/skills-center.md │ ├─── User info ─────────────────────────────────── │ └── GET /users/me │ └─── Not supported ───────────────────────────────────── ├── Pull Request (ModelScope has no PR system) └── Delete tags/branches (no API) ``` ## 1. Resource Search ### OpenAPI Method **Search models:** ```bash curl "$MODELSCOPE_ENDPOINT/openapi/v1/models?search=Qwen&sort=downloads&page_size=20" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" ``` **Search parameters:** | Parameter | Description | Example | |------|------|------| | `search` | Keyword | `"Qwen"`, `"text generation"` | | `owner` | Author/organization | `"Qwen"`, `"ZhipuAI"` | | `sort` | Sort | `default`, `downloads`, `likes`, `last_modified` | | `page_size` | Items per page (max 50) | `20` | | `filter.task` | Task type | `text-generation`, `image-captioning` | | `filter.library` | Framework | `pytorch`, `safetensors`, `diffusers` | | `filter.model_type` | Model type | `qwen3_moe`, `glm4v`, `llama` | | `filter.license` | License | `Apache License 2.0`, `MIT License` | **Common filter combinations:** ```bash # PyTorch text-generation models, sorted by downloads /models?filter.library=pytorch&filter.task=text-generation&sort=downloads # All models from a specific author /models?owner=Qwen&sort=last_modified ``` **Search datasets:** ```bash curl "$MODELSCOPE_ENDPOINT/openapi/v1/datasets?search=dialogue&sort=downloads&page_size=10" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" ``` **OpenAPI response structure (model list):** ```json {"data": {"models": [{"id": "Qwen/...", "downloads": N, "likes": N, "license": "...", "tasks": [...]}], "total_count": N}} ``` ### SDK Method ```python from modelscope.hub.api import HubApi api = HubApi() # Search models → dict{"Models": [...], "TotalCount": N} result = api.list_models(owner_or_group="Qwen", page_number=1, page_size=20) for m in result["Models"]: print(f"{m['Path']} ({m['Downloads']} downloads)") # Search datasets → dict{"datasets": [...], "total_count": N} result = api.list_datasets(owner_or_group="AI-ModelScope", page_number=1, page_size=20) for d in result["datasets"]: print(f"{d['id']} ({d['downloads']} downloads)") ``` > **SDK vs OpenAPI field name differences**: SDK `list_models` returns PascalCase (`Path`, `Downloads`), while OpenAPI `/models` returns snake_case (`id`, `downloads`). `list_datasets` is snake_case on both sides. ## 2. View Details ### OpenAPI Method ```bash # Model details curl "$MODELSCOPE_ENDPOINT/openapi/v1/models/Qwen/Qwen2.5-72B-Instruct" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" # Dataset details curl "$MODELSCOPE_ENDPOINT/openapi/v1/datasets/AI-ModelScope/alpaca-gpt4-data-zh" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" ``` ### SDK Method (more complete info) ```python info = api.model_info("Qwen/Qwen2.5-72B-Instruct") # info.readme_content - Full README text # info.tags - Tag list # info.downloads - Download count # info.siblings - File list (incl. rfilename, size, sha) # info.visibility - Visibility (1=private, 5=public) info = api.dataset_info("AI-ModelScope/alpaca-gpt4-data-zh") ``` ### Get User Info ```bash curl "$MODELSCOPE_ENDPOINT/openapi/v1/users/me" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" ``` ## 3. Repository Management ### Create Repository ```bash # CLI (--repo-type required) ms create owner/repo-name --repo-type model ms create owner/repo-name --repo-type model --visibility private ms create owner/dataset-name --repo-type dataset ``` ```python # SDK: general creation — note that create_repo's visibility uses the string "public"/"private" api.create_repo( repo_id="owner/repo-name", repo_type="model", # "model" or "dataset" visibility="public", # "public" or "private" (string, not integer) license="Apache License 2.0", exist_ok=True ) # Model-specific — create_model/create_dataset visibility uses integers 1=private, 5=public api.create_model(model_id="owner/model-name", visibility=5) # Dataset-specific api.create_dataset( dataset_name="dataset-name", namespace="owner", visibility=5 ) # AIGC/LoRA models: via the SDK's aigc_model parameter (create_repo/create_model); no corresponding CLI flag ``` ### Check Whether a Repository Exists ```python exists = api.repo_exists(repo_id="owner/repo", repo_type="model") ``` ### Set Visibility ```python # visibility uses the string "public" / "private" (not an integer) api.set_repo_visibility(repo_id="owner/repo", repo_type="model", visibility="private") ``` ### Delete Repository > ⚠️ **Repository deletion has been restricted by the platform to the web console only**: `api.delete_repo(...)` returns 401 under token authentication ("Deletion is restricted to web console") and cannot be deleted programmatically. Please perform this operation on the web at https://modelscope.cn. ## 4. File Operations ### List Files ```python files = api.get_model_files( model_id="Qwen/Qwen2.5-7B-Instruct", revision="master", recursive=True )