---
title: "Import a stock candidate or a curated SFX-pack sound"
method: POST
path: "/v1/resources/import"
tags: ["resources"]
---

# Import a stock candidate or a curated SFX-pack sound

`POST /v1/resources/import`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/resources/import`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `media:write`)
  - API key in header `PAYMENT-SIGNATURE`

Two lanes. STOCK { projectId, candidateId }: import a candidate returned by search_resources into a project as an org-owned media item (preserving provider/externalId/license provenance; bytes deduped across orgs). Async: returns { id, status:'importing' }; status flips to complete when the import finishes (poll GET /media/:id). A candidate whose 7-day search cache has expired returns 422 — re-search. PACK { kind:"sfx-pack", id:<soundId> }: mint/return the org media item for a curated CC0 SFX-pack sound (soundId from list_catalog's sfx[]) — returns { id, status:'ready' } immediately to place as a normal sfx clip. Idempotent per (org, soundId); an unknown soundId is a 422. Pack imports are FREE: no plan feature required, and an x402 payment is released unsettled (no charge). PRICE of a stock import for a keyed (API-key / session) caller: 0 credits — the resource_import entitlement is a plan grant, not a meter (get_account reports `entitlements.resource_import.listUsdPerUnit: 0`); the imported bytes count toward the `storage` gauge. Only an unkeyed x402 caller pays the $0.01 import tier.

## Request body

- ResourceImportRequest: POST /resources/import body — stock candidate lane { projectId, candidateId } OR curated pack lane { kind:"sfx-pack"|"music-pack", id }.
  - `kind` 'sfx-pack' | 'music-pack'
  - `id` string
  - `projectId` string
  - `candidateId` string

## Response `201`

Import reserved.

- ResourceImportResponse: POST /resources/import response.
  - `id` string, required
  - `status` 'importing' | 'ready', required

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required — billing_required or x402 payment_*.
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)