---
title: "Create Media asynchronously"
method: POST
path: "/media/bulk"
tags: ["Medias"]
---

# Create Media asynchronously

`POST /media/bulk`

## Request

- Base URL: `https://open.shopline.io/v1`
- URL: `https://open.shopline.io/v1/media/bulk`
- Auth: HTTP bearer

Requires the media create permission. Creates Media asynchronously from staged uploads or external public image URLs. client_reference_id must be unique within this request, contain 1-128 letters, digits, underscores, or hyphens, and is correlation data rather than an idempotency key. A valid batch returns HTTP 200 for full success, partial success, or when every item has an item-level error.<br> 需要圖像建立權限。系統會從暫存上傳或外部公開圖片網址非同步建立圖像。client_reference_id 在同一請求中必須唯一，長度為 1-128 個字元，且只能包含英文字母、數字、底線或連字號；此欄位 僅供關聯結果，並非冪等鍵。有效的批次請求無論全部成功、部分成功，或所有項目皆發生項目層級錯誤， 均回傳 HTTP 200。

## Request body

- object
  - `medias` object[], required: Media sources processed independently; each reference must be unique.<br> 獨立處理的圖像來源；每個參考值必須唯一。
    - `client_reference_id` string, required: Caller-generated value used to match this item to its result. It must be unique within this request and is not an idempotency key.<br>呼叫端產生的值，用於將此項目與結果配對。 此值在同一請求中必須唯一，且並非冪等鍵。
    - `source` union, required: One staged-upload or external-URL image source.<br> 一個暫存上傳或外部網址圖像來源。
      - object: An image uploaded through the staged-upload endpoint.<br> 透過暫存上傳端點上傳的圖像。
        - `type` 'staged_upload', required: Staged-upload processing path.<br>暫存上傳處理流程。
        - `resource_url` string, uri, required: resource_url returned by the staged-upload endpoint.<br> 暫存上傳端點回傳的 resource_url。
      - object: An external image that SHOPLINE will fetch and copy.<br> 由 SHOPLINE 擷取並複製的外部圖像。
        - `type` 'external_url', required: External-URL processing path.<br>外部網址處理流程。
        - `url` string, uri, required: Public URL of the original JPEG, PNG, or GIF.<br> 原始 JPEG、PNG 或 GIF 圖像的公開網址。

## Response `200`

Accepted Media or per-item errors<br>已接受的圖像或各項目錯誤

- object
  - `data` object
    - `items` BulkMediaResult[]
      - `client_reference_id` string: Client-provided correlation ID<br>客戶端提供的關聯 ID
      - `media_id` string, nullable: Created Media ID; null when the item fails<br>建立的圖像 ID；項目失敗時為 null
      - `processing_status` 'PENDING' | 'FAILED', nullable: Initial processing status<br>初始處理狀態
      - `processing_error` object, nullable: Item-level error; null when accepted<br>項目層級錯誤；已接受時為 null
        - `code` 'STAGED_OBJECT_NOT_FOUND' | 'INVALID_FILE_SIZE' | 'INVALID_REQUEST' | 'EXTERNAL_URL_INVALID' | 'PROCESSING_FAILED', required: Machine-readable error code<br>機器可讀的錯誤代碼
        - `message` string, required: Human-readable error message<br>人類可讀的錯誤訊息
  - `error` PublicApiError
    - `code` string, required: Machine-readable error code<br>機器可讀的錯誤代碼
    - `message` string, required: Human-readable error message<br>人類可讀的錯誤訊息
  - `trace_id` string

## Other responses

- `400`: INVALID_REQUEST, INVALID_CLIENT_REFERENCE, or DUPLICATE_CLIENT_REFERENCE<br>請求或參考 ID 無效
- `413`: BATCH_SIZE_EXCEEDED<br>超出批次大小限制

## Changes

- **2026-11-03** `d2518391b149`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shoplineapp/apis/shopline-open-api/changes/media/bulk/post.md)

---

[API](https://skmtc.dev/shoplineapp/apis/shopline-open-api.md) - [All operations](https://skmtc.dev/shoplineapp/apis/shopline-open-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shoplineapp/apis/shopline-open-api/revisions/d2518391b149?raw)