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

# Uploads

> Register a reference image, video or audio file and get the asset id a generation can use.

Models that take references (image-to-video, first and last frames, motion control, lip sync,
voice reference) take **asset ids**. The upload flow gives you one for a file on your side, and
every generation output already has one, so chaining generations needs no upload at all.

<Steps>
  <Step title="Register the file">
    ```bash theme={null}
    curl https://api.ekly.ai/v1/uploads \
      -H "Authorization: Bearer $EKLY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "filename": "reference.png", "content_type": "image/png", "size_bytes": 482133 }'
    ```

    The response has `asset_id` (what you will pass to a generation), `upload_url` (where to PUT
    the bytes) and `required_headers` (send them exactly). The size you declare is binding; a PUT
    with a different number of bytes is rejected. For video and audio, send `duration_seconds` too.
  </Step>

  <Step title="PUT the file">
    ```bash theme={null}
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: image/png" \
      -H "x-goog-content-length-range: 0,482133" \
      --data-binary @reference.png
    ```

    Send the `required_headers` from the previous response exactly as given; the declared size is
    part of the signature, so a file of a different size is refused. Upload URLs expire after ten
    minutes. Register the file again if you miss it.
  </Step>

  <Step title="Use the asset id in a generation">
    ```json theme={null}
    {
      "prompt": "The fox turns its head and looks at the camera",
      "model": "seedance-2-5-fal",
      "first_frame": "a1b2c3d4-…"
    }
    ```

    `GET /v1/models/{id}` names the reference inputs each model and mode accept (`first_frame`,
    `reference_images`, `motion_video`, …) and which are required.
  </Step>
</Steps>

## Accepted files

Images (PNG, JPEG, WebP), video (MP4, MOV, WebM) and audio (MP3, WAV, M4A). Per-model limits on
count, duration and frame rate come from `GET /v1/models/{id}`; a request that breaks them is
rejected before any credit is reserved.

An asset id must belong to your organization and be visible to the key's creator, the same rule
the app's Assets library applies. Uploaded files appear in that library like any other upload.


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