---
title: "Explicitly describe one completed controlled upload."
method: POST
path: "/v1/start_external_media_analysis"
tags: ["External Authorization"]
---

# Explicitly describe one completed controlled upload.

`POST /v1/start_external_media_analysis`

## Request

- Base URL: `https://partner.mindupload.app`
- URL: `https://partner.mindupload.app/v1/start_external_media_analysis`
- Auth: API key in header `X-Partner-Key`

## Request body

- object
  - `preferred_language` string, nullable: BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages.
  - `access_token` string, required: Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users.
  - `installation_id` string, required: Your stable opaque identifier for this app installation.
  - `external_subject` string, required: Your stable opaque identifier for the person authorizing this installation.
  - `clone_id` string, required: AI consciousness id as returned by clone operations.
  - `upload_id` string, required: Server-issued controlled upload reference returned by request_external_media_upload; never a URL.

## Response `200`

Result envelope — check the success field.

- object
  - `success` boolean: Whether the call succeeded.
  - `error_message` string, nullable: Human-readable reason when success is false.
  - `error_code` string
  - `media` object, nullable
    - `media_id` string, required
    - `media_type` string, required: The kind of media: `image`, `video`, or `audio`.
    - `analysis_status` string, required: How far this attachment's description had got at the moment this call returned: `pending` when it was just started, `processing` while it is being written, `completed` when it is already available, and `failed` when this attachment could not be started at all — the other entries are unaffected and the attachment is still sendable. The value is never updated afterwards and there is nothing to poll: calling again to see a newer one is a fresh charged request that buys no more than sending the message does.
    - `analysis_text` string, nullable, required
    - `media_url` string, required: Media URL returned by this operation; use signed read URLs unchanged.
    - `content_type` string, required
    - `file_size_bytes` integer, required
    - `expires_at` integer, required: UNIX timestamp when this resource or capability expires.
    - `draft_expires_at` integer, nullable, required

## Other responses

- `400`: Invalid request payload.
- `401`: Missing or invalid partner key.
- `403`: Partner is not authorized for this operation.
- `429`: Rate limit exceeded — retry later.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mindupload/apis/mind-upload-partner-api.md) · [All operations](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mindupload/apis/mind-upload-partner-api/revisions/0371bdf78533?raw)