ModelScope Studio Cover Upload

Upload the user's chosen image to the exact Studio they specified, then verify the stored cover. Existing authorization to set that cover is sufficient; do not ask again. Ask only for a missing image, target, or usable credential. Do not regenerate, crop, or alter a supplied image unless requested.

Preferred workflow

Use scripts/upload_cover.py, with the token in a process environment variable:

python scripts/upload_cover.py --endpoint https://modelscope.cn --studio owner/repo --file /absolute/path/cover.png

Default token variable: MODELSCOPE_API_KEY. MODELSCOPE_API_TOKEN is also accepted as a fallback environment variable. Never put a token in the command's arguments, script, repository remote URL, skill, or output. Use the endpoint and credential for the selected site; domestic and international credentials are separate. Do not send a domestic token to the international site to test it.

The helper reads current Studio settings, obtains a STUDIO_COVER signed upload URL, PUTs the exact file bytes without bearer credentials, obtains the image download URL, PATCHes only cover_image, and verifies both settings readback and the saved image URL. It never changes visibility, SDK, hardware, or secrets, and it does not redeploy the application.

The general /openapi/v1/files/upload endpoint returns a file ID. A file ID is not a cover URL: passing it directly as cover_image produced HTTP 400 in a live test. Use an actual downloadable image URL.

Evidence and API stability

Read references/frontend-contract.md when adapting or diagnosing the upload flow. The resource-management upload endpoints were observed in the website's frontend, not guaranteed by public OpenAPI documentation. The Studio settings endpoint has public documentation. Do not describe the entire upload chain as a publicly documented stable API.

If the internal endpoints return 401/403, stop token retries and use the user's already logged-in Studio edit page through an available browser skill. Do not extract cookie stores or invent authentication. On schema/signature errors, inspect the current edit-page resources or its actual upload traffic, then adapt the helper. Do not brute-force endpoint variants. An expired signed slot can be refreshed once; after a repeated failure, report the exact failing stage and retain the user's image.

Before any browser file upload, read that browser tool's upload guidance. Upload only the explicitly chosen cover. Confirm the image is accepted, save through the edit page, then verify the new cover by readback or visible preview. Preserve unrelated settings. If saving is uncertain, read back the current cover before trying another mutation.

Validation and delivery

Check the file exists and is PNG/JPEG. The observed form requires width above 400px and height above 220px; the helper accepts files up to 5 MiB. Preserve the user's chosen aspect ratio, even if it is not precisely 16:9. Request resizing only when the platform actually rejects the image and the user's scope does not authorize changing it.

Confirm a real image URL is saved, not an upload ID or expiring PUT URL. Report the target Studio and the supplied local file. Do not say "completed" based only on a successful storage upload. Do not expose signed upload URLs or tokens. Never leave scaffolding placeholders in this skill.