| name | modelscope-api |
| description | Use when Codex needs to work with Alibaba ModelScope models, datasets, Skills, MCP services, Studios, OpenAPI endpoints, SDK/CLI resource downloads, file uploads, or authenticated ModelScope account operations. |
ModelScope API
Overview
Use ModelScope OpenAPI for platform queries and management, and use the official ModelScope SDK/CLI for downloading model or dataset resources. Keep credentials outside the skill and outside committed files; each user should configure their own token in the environment.
The official OpenAPI source is bundled at references/openapi.json. Start with references/api-summary.md for endpoint selection, then inspect openapi.json only when exact schema details are required.
For downloads, start with references/sdk-downloads.md. Context7 documentation for /modelscope/modelscope confirms that the official CLI supports modelscope download with --model, --dataset, --revision, --cache_dir, --local_dir, --include, --exclude, and optional file paths.
Token Setup
Require one of these environment variables before authenticated calls:
export MODELSCOPE_API_TOKEN="..."
MODELSCOPE_TOKEN is accepted as a fallback for local compatibility. Never write tokens into SKILL.md, scripts, examples, shell history snippets, logs, or files committed with the skill.
Quick Start
Check the local environment first:
python3 modelscope-api/scripts/check_setup.py
Use the OpenAPI helper for platform API calls:
python3 modelscope-api/scripts/modelscope_api.py GET /users/me
python3 modelscope-api/scripts/modelscope_api.py GET /models --query search=Qwen --query page_size=5
python3 modelscope-api/scripts/modelscope_api.py GET /models/qwen/Qwen3-8B
Use the SDK/CLI download helper for resources:
python3 modelscope-api/scripts/modelscope_download.py model qwen/Qwen3-8B --local-dir ./Qwen3-8B --dry-run
python3 modelscope-api/scripts/modelscope_download.py dataset modelscope/test-dataset --cache-dir ./ms-cache --dry-run
Use --dry-run before mutating calls or when showing examples. It redacts the authorization header:
python3 modelscope-api/scripts/modelscope_api.py POST /studios --data '{"owner":"my-user","repo_name":"demo"}' --dry-run
For file uploads:
python3 modelscope-api/scripts/modelscope_api.py POST /files/upload --file file=/path/to/archive.zip
Workflow
- Decide whether the task is metadata/management or resource download.
- For metadata and management, read
references/api-summary.md; use scripts/modelscope_api.py.
- For model or dataset downloads, read
references/sdk-downloads.md; use scripts/modelscope_download.py or the official modelscope download CLI directly.
- For setup issues, read
references/setup.md; use scripts/check_setup.py.
- For skill publishing, read
references/publishing-skills.md; use scripts/package_skill.py.
- For schema precision, search
references/openapi.json for operationId, path, or schema name.
- Confirm a token is available in
MODELSCOPE_API_TOKEN when the operation needs authenticated access; if not, ask the user to configure it.
- Use
--dry-run for POST, PUT, PATCH, DELETE, deployments, uploads, secret changes, skill publishing, and large downloads before sending the request.
- Summarize returned JSON in user language; include
request_id when present.
Common Tasks
Search Models Or Datasets
Use GET /models or GET /datasets with search, owner, pagination, and filter.* query parameters.
python3 modelscope-api/scripts/modelscope_api.py GET /models --query search=Qwen --query sort=downloads --query page_size=10
python3 modelscope-api/scripts/modelscope_api.py GET /datasets --query search=中文语料库 --query page_size=5
Download Models Or Datasets
Use the official SDK/CLI, not OpenAPI. The OpenAPI bundled here does not expose model or dataset file download endpoints.
python3 modelscope-api/scripts/modelscope_download.py model qwen/Qwen3-8B --local-dir ./Qwen3-8B --dry-run
python3 modelscope-api/scripts/modelscope_download.py dataset modelscope/test-dataset --cache-dir ./ms-cache --dry-run
Remove --dry-run only after checking expected size, output path, include/exclude filters, and user intent.
Check Setup
Run the setup check before first use or when authentication/downloads fail:
python3 modelscope-api/scripts/check_setup.py --json
Read references/setup.md to interpret missing token or missing CLI results.
Manage Studios
Use the hardware, SDK version, and base image endpoints before creating or updating a Studio. Changes to hardware, SDK, base image, or runtime config may require redeployment.
Use secret endpoints for sensitive values and variable endpoints only for non-sensitive values. Studio variables return plaintext values.
Publish Or Update ModelScope Skills
Use POST /files/upload to upload a zip file first, then use the returned file ID as skill_file in POST /skills or PATCH /skills/{owner}/{skill_name}/settings.
The OpenAPI states the zip package must be at most 5 MB and its root must contain exactly one SKILL.md.
Package and validate this skill shape with:
python3 modelscope-api/scripts/package_skill.py modelscope-api --output /tmp/modelscope-api-skill.zip
Read references/publishing-skills.md before publishing or updating a Skill on ModelScope.
References
references/api-summary.md: compact endpoint and schema guide.references/sdk-downloads.md: ModelScope SDK/CLI download guide.references/setup.md: local environment and token setup guide.references/publishing-skills.md: packaging, uploading, creating, and updating ModelScope Skills.references/openapi.json: complete OpenAPI 3.1.1 source from ModelScope.scripts/modelscope_api.py: dependency-free CLI for authenticated requests.scripts/modelscope_download.py: wrapper around the official modelscope download CLI.scripts/check_setup.py: setup checker for token, Python, and ModelScope CLI.scripts/package_skill.py: package validator for ModelScope Skill zip uploads.
