> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Media from URL

> Add an image or video at a public URL to your media library

## Overview

Adds the file at a public `https` URL to your team's media library, so you can use it in any create endpoint. The call answers `202` right away with the new `mediaId`; the file is downloaded after the response. Poll [Get Media](/api-reference/media/details) until `status` is `COMPLETED`, then pass the id as `media`. Or pass a `webhook` (with optional `metadata`) to be told once the import is `COMPLETED` or `FAILED`: see [media webhooks](/guides/webhooks#media-webhooks).

<Info>
  JPEG, PNG, WEBP, GIF, MP4, MOV or WEBM, up to **100 MB**. The type is read from the file itself, not from the URL or the host's `Content-Type`. The file counts against your plan's storage. Importing is free.
</Info>

The URL must be public: local, private-network and plain `http` addresses are refused with `400` before anything is created, and every redirect is checked the same way. A URL that cannot be downloaded, a file of another type, one over 100 MB or one that does not fit your storage leaves the media `FAILED`, with the reason in its `error`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hooked.so/v1/media/import" \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{ "url": "https://cdn.example.com/products/serum.png", "name": "Serum bottle" }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.hooked.so/v1/media/import", {
    method: "POST",
    headers: { "x-api-key": process.env.HOOKED_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ url: "https://cdn.example.com/products/serum.png", name: "Serum bottle" }),
  });
  const { data } = await response.json();
  // Poll GET /v1/media/{mediaId} until status is COMPLETED
  console.log(data.mediaId, data.status);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.hooked.so/v1/media/import",
      headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
      json={"url": "https://cdn.example.com/products/serum.png", "name": "Serum bottle"},
  )
  data = response.json()["data"]
  print(data["mediaId"], data["status"])
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "message": "Import started",
    "data": {
      "mediaId": "cm4x9r2t50007ab12gh34ij78",
      "status": "PROCESSING"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "message": "url: Must be a public https URL"
  }
  ```
</ResponseExample>

## Errors

| Status | Message | Cause |
| - | - | - |
| 400 | `Invalid JSON body` | The body is not JSON. |
| 400 | `url: Required` | No `url`. |
| 400 | `url: Must be a public https URL` | Not a URL, not `https`, or a local or private address. |
| 400 | `webhook: Must be a valid HTTPS URL` | `webhook` is not a public `https` URL. |
| 400 | `metadata: Metadata cannot exceed 5KB` | `metadata` is larger than 5 KB once serialized. |
| 401 | `code: "not_authenticated"` | Missing or invalid `x-api-key`. |
| 403 | `code: "entitlement_required"` | Your team does not have the Hooked app product. |

Problems with the file itself (unreachable, wrong type, too large, no storage left) do not answer an error here: the media becomes `FAILED` in [Get Media](/api-reference/media/details), and its `error` says which.

<Tip>
  The file is on your own machine? Use [Upload Media](/api-reference/media/upload) instead.
</Tip>


## OpenAPI

````yaml POST /v1/media/import
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
tags:
  - name: Videos
    description: Create projects, follow them and render videos
  - name: Account Analysis
    description: Analyze TikTok and YouTube accounts
  - name: Channels
    description: Connected social accounts you publish to
  - name: Publish
    description: Schedule videos to your connected accounts
  - name: Images
    description: 'Image editing: background removal and expansion'
  - name: Media
    description: 'Your media library: list, import from a URL, upload a file'
  - name: Avatars
    description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
  /v1/media/import:
    post:
      tags:
        - Media
      summary: Import Media from URL
      description: >-
        Adds an image or video at a public https URL to your library. Answers
        202 at once with the media id; the file is downloaded after the
        response. Poll Get Media until `status` is `COMPLETED` (use the id in
        any create endpoint) or `FAILED` (its `error` says why), or pass a
        `webhook` to be told (`media.completed` / `media.failed`). JPEG, PNG,
        WEBP, GIF, MP4, MOV or WEBM, up to 100 MB, counted against your plan's
        storage. Free.
      operationId: importMedia
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                  description: >-
                    Public https URL of the file. Private, local and plain http
                    addresses are refused.
                name:
                  type: string
                  description: Name in your library. Defaults to the file name in the URL.
                webhook:
                  type: string
                  maxLength: 500
                  description: >-
                    Public https URL told once when the media is `COMPLETED` or
                    `FAILED` (events `media.completed` / `media.failed`, signed
                    like every Hooked webhook). See
                    [Webhooks](/guides/webhooks#media-webhooks).
                metadata:
                  type: object
                  additionalProperties: true
                  description: >-
                    Any JSON object of your own (max 5 KB). Sent back in the
                    webhook payload.
            example:
              url: https://cdn.example.com/products/serum.png
              name: Serum bottle
      responses:
        '202':
          description: Import started
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      mediaId:
                        type: string
                        description: The new media. Follow it with GET /v1/media/{mediaId}.
                      status:
                        type: string
                        enum:
                          - PROCESSING
                        description: Always `PROCESSING` here
              example:
                success: true
                message: Import started
                data:
                  mediaId: cm4x9r2t50007ab12gh34ij78
                  status: PROCESSING
        '400':
          description: Invalid body or URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError400'
              example:
                success: false
                message: 'url: Must be a public https URL'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/EntitlementRequired'
        '409':
          $ref: '#/components/responses/IdempotencyInProgress'
        '422':
          $ref: '#/components/responses/IdempotencyMismatch'
        '429':
          $ref: '#/components/responses/RateLimited429'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
              example:
                success: false
                message: Failed to start the import
      security:
        - ApiKeyAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Makes the request safe to retry. 1-255 printable ASCII characters, one
        per operation (your job id, or a UUID you store), reused on every retry.
        Within 24 hours the same key with the same body answers with the first
        response and the header `Idempotent-Replayed: true`, without running or
        charging again. Keys are scoped to your team and the endpoint. 5xx
        answers and refusals before anything ran (401, 402, 403, 409, 429) are
        not kept. See [Idempotency](/guides/idempotency).
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[\x20-\x7E]+$
      example: order-1042-video
  schemas:
    ValidationError400:
      type: object
      description: >-
        The request is invalid. `message` is `<field>: <reason>` when a field is
        to blame.
      properties:
        success:
          type: boolean
          enum:
            - false
        message:
          type: string
      required:
        - success
        - message
      example:
        success: false
        message: 'webhook: Must be a valid HTTPS URL'
    Error500:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        message:
          type: string
        error:
          type: string
          description: Present on some endpoints
      example:
        success: false
        message: Internal server error
    Error401:
      type: object
      description: Missing or invalid `x-api-key`.
      properties:
        code:
          type: string
          enum:
            - not_authenticated
        message:
          type: string
          example: Not authenticated
        errorCode:
          type: string
          enum:
            - NOT_AUTHENTICATED
        details:
          type: object
          additionalProperties:
            type: string
      example:
        code: not_authenticated
        message: Not authenticated
        errorCode: NOT_AUTHENTICATED
        details:
          x-api-key: Header not provided or API Key invalid
    EntitlementRequired403:
      type: object
      description: >-
        Valid key, but the team does not have the product this endpoint belongs
        to.
      properties:
        code:
          type: string
          enum:
            - entitlement_required
        error:
          type: string
          enum:
            - entitlement_required
        message:
          type: string
        product:
          type: string
          example: app
      required:
        - code
        - error
        - message
        - product
      example:
        code: entitlement_required
        error: entitlement_required
        message: This endpoint requires the "app" product.
        product: app
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401'
    EntitlementRequired:
      description: The team does not have the product this endpoint needs
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EntitlementRequired403'
    IdempotencyInProgress:
      description: >-
        A request with the same `Idempotency-Key` is still running. Retry in a
        few seconds.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
              code:
                type: string
              message:
                type: string
              details:
                type: object
                additionalProperties: true
            required:
              - success
              - code
              - message
          example:
            success: false
            code: idempotency_conflict
            message: A request with this Idempotency-Key is still in progress
            details: {}
    IdempotencyMismatch:
      description: >-
        The `Idempotency-Key` was already used with a different body. Use a new
        key for a new request.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
              code:
                type: string
              message:
                type: string
              details:
                type: object
                additionalProperties: true
            required:
              - success
              - code
              - message
          example:
            success: false
            code: idempotency_mismatch
            message: Idempotency-Key was used with a different request
            details: {}
    RateLimited429:
      description: >-
        Your team is over a rate limit: 30 POST requests per minute, 120 other
        requests per minute, or 3 downloads of your URLs running at once.
        Nothing ran and nothing was charged: wait `Retry-After` seconds and send
        the request again. See [Rate
        limits](/guides/error-handling#rate-limits-429).
      headers:
        Retry-After:
          description: Seconds to wait before sending again.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: The limit of the bucket you hit (not sent for the download cap).
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: 'Requests left in this window: 0 (not sent for the download cap).'
          schema:
            type: integer
        X-RateLimit-Reset:
          description: >-
            When the window ends, in Unix seconds (not sent for the download
            cap).
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
              errorCode:
                type: string
                enum:
                  - RATE_LIMITED
              message:
                type: string
              retryAfterSeconds:
                type: integer
            required:
              - success
              - errorCode
              - message
              - retryAfterSeconds
          example:
            success: false
            errorCode: RATE_LIMITED
            message: >-
              Rate limit exceeded: 30 POST requests per minute per team. Retry
              after 12 s.
            retryAfterSeconds: 12
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.