API Documentation

Welcome to the Y Converter API. You can use our API to access image conversion endpoints, which can help you convert images between formats like JPG, PNG, WEBP, AVIF, and more programmatically.

Base URL: https://converter.yahiaashraf.com/api/v1

Authentication

The API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Authentication to the API is performed via the token parameter in the request body or query string.

Alternatively, you can send the key as a Bearer token using the Authorization HTTP header.

Using token parameter

curl -X POST https://converter.yahiaashraf.com/api/v1/convert \
  -d "token=YOUR_API_KEY" \
  -d "img_url=https://example.com/image.jpg"

Using Authorization header

curl -X POST https://converter.yahiaashraf.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "img_url=https://example.com/image.jpg"

Convert Image

POST /convert

Converts an image from a URL to a specified format.

Parameters

Parameter	Type	Required	Description
img_url	string	Yes	The public URL of the image you want to convert.
target_format	string	No	Target image format (e.g., `webp`, `png`). Defaults to `webp`.
quality	integer	No	Image quality (1-100). Default is 90.
width	integer	No	Resize width in pixels.
height	integer	No	Resize height in pixels.
resize_mode	string	No	Resize strategy: `fit` (default), `crop`, `scale`.
background	string	No	Hex color (e.g. `#ffffff`) to fill transparency.
preserve_metadata	boolean	No	Whether to preserve EXIF metadata (e.g. `true`, `false`).

Supported Formats

jpg / jpeg png webp avif gif svg ico

Responses

Success Response (200 OK)

JSON Response

{
  "success": true,
  "data": {
    "download_link": "https://converter.yahiaashraf.com/storage/converted/image_12345.webp",
    "meta": {
      "file_size": 102400,
      "file_size_formatted": "100 KB",
      "format": "webp",
      "width": 800,
      "height": 600,
      "processed_at": "2023-10-27T10:00:00+00:00"
    }
  }
}

Error Response (422 Unprocessable Entity)

JSON Response

{
  "success": false,
  "message": "The img_url field is required.",
  "errors": {
    "img_url": [
      "The img_url field is required."
    ]
  }
}

Code Examples

<?php

$client = new \GuzzleHttp\Client();

$response = $client->post('https://converter.yahiaashraf.com/api/v1/convert', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
    'form_params' => [
        'img_url' => 'https://example.com/image.jpg',
        'target_format' => 'webp',
        'quality' => 85,
    ],
]);

echo $response->getBody();

import requests

url = "https://converter.yahiaashraf.com/api/v1/convert"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept": "application/json"
}
data = {
    "img_url": "https://example.com/image.jpg",
    "target_format": "webp",
    "quality": 85
}

response = requests.post(url, headers=headers, data=data)

print(response.json())

const axios = require('axios');

async function convertImage() {
  try {
    const response = await axios.post('https://converter.yahiaashraf.com/api/v1/convert', {
      img_url: 'https://example.com/image.jpg',
      target_format: 'webp',
      quality: 85
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json'
      }
    });

    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
}

convertImage();

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request.

200 OK

Request was successful and the response body contains the requested data.

401 Unauthorized

API key is missing or invalid. Please check your token.

422 Unprocessable

Validation error. Check your input parameters (e.g. invalid URL or format).

429 Too Many Requests

Rate limit exceeded for your subscription plan. Upgrade for higher limits.

500 Server Error

Something went wrong on our end. Please contact support if this persists.