yourimageshare-api/elixir

Official Elixir SDK for the YourImageShare upload API. One dependency (Req, for HTTP + native streaming multipart), Elixir 1.14+.

• Get an API key: sign in and open the API tab at yourimageshare.com/my-account.
• Full HTTP reference: yourimageshare.com/about/api or API.md in this repo.
• Same API, same result shapes, in JavaScript/TypeScript, Python, PHP, Go, Rust, and Ruby too.

Install

Add to mix.exs:

def deps do
  [
    {:yourimageshare, "~> 1.0"}
  ]
end

Usage

client = YourImageShare.Client.new("YOUR_API_KEY")

# Upload a file by path
{:ok, result} = YourImageShare.Client.upload(client, "photo.jpg")
result.direct
#=> "https://yourimageshare.com/ib/aB3xY9qRz1"

# Upload with auto-delete after 1 hour
YourImageShare.Client.upload(client, "photo.jpg", expires_in: 3600)

# Upload from any Enumerable/File.Stream (a network stream, an in-memory buffer, ...)
# YourImageShare.Client.upload_stream(client, stream, "photo.jpg")

# List your uploads (paginated, 50 per page)
{:ok, listing} = YourImageShare.Client.list(client)
Enum.each(listing.data, fn item -> IO.puts("#{item.id} #{item.direct}") end)

# Delete an upload
YourImageShare.Client.delete(client, result.id)

Error handling

Every function returns {:ok, result} | {:error, %YourImageShare.APIError{}} by default - the direct equivalent of Go's (result, error) return, just tagged-tuple style:

case YourImageShare.Client.upload(client, "photo.jpg") do
  {:ok, result} -> IO.puts(result.direct)
  {:error, %YourImageShare.APIError{status: status, message: message}} ->
    IO.puts("#{status}: #{message}")
end

Every function also has a bang (!) variant that raises YourImageShare.APIError instead, for callers who prefer that style (upload!/3, upload_stream!/4, list!/2, delete!/2):

result = YourImageShare.Client.upload!(client, "photo.jpg")

API

YourImageShare.Client.new(api_key, opts \\ [])

opts[:base_url] overrides the API base URL (mainly for testing). opts[:req_options] merges extra options into every request (e.g. receive_timeout: or a custom :finch pool).

Client.upload(client, file_path, opts \\ [])

Streams the file from disk via File.stream!/1 - doesn't buffer the whole thing in memory. opts[:expires_in] is seconds, 60 to 2,592,000 (30 days); omit for a permanent upload. Returns an %UploadResult{} with id, type, path, src, direct, expires_at.

Client.upload_stream(client, stream, filename, opts \\ [])

Same as upload/3, but from any Enumerable/File.Stream instead of a file path.

Client.list(client, opts \\ [])

Returns a %ListResult{} with data (a list of %ListedUpload{} - id, type, title, path, src, direct, expires_at, created_at) and meta (%ListMeta{} - current_page, last_page, total). opts[:page] < 2 fetches the first page.

Client.delete(client, id)

Returns {:error, %APIError{}} on a 404/401; :ok on success.

Rate limits

20 requests/minute and 500/day per key by default (2,000/day per IP as a backstop). Not currently surfaced on the return values from this SDK - read the X-RateLimit-Limit/X-RateLimit-Remaining response headers yourself if you need them, or open an issue to request them on the result types.

License

MIT

Support

yourimageshare.com/contact