Skip to main content
POST
/
v1
/
uploads
/
images
curl --request POST \
  --url https://toapis.com/v1/uploads/images \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@/path/to/your/image.jpg'

{
  "success": true,
  "message": "",
  "data": {
    "id": "upload_abc12345",
    "url": "https://files.toapis.com/uploads/123/1737568800_abc12345.jpg",
    "mime_type": "image/jpeg",
    "size": 89234
  }
}
The docs Playground does not support file uploads: Please use the cURL, Python, or JavaScript code examples below for testing.
Important Change: For better performance and cost control, we no longer support passing base64 image data directly in generation APIs. Please use this endpoint to upload images first, then use the returned URL in generation requests.

​
Why Upload First?

  1. Performance - Base64 encoding inflates data by 33%, uploading first significantly reduces request payload size
  2. Reusability - Upload once, use the URL multiple times without re-transmitting

​
Workflow

​
Authorizations

​
Authorization
string
required
Use Bearer Token for authenticationGet your API Key: Visit API Key Management
Authorization: Bearer YOUR_API_KEY

​
Body

​
file
file
required
Image fileSupported formats:
  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)
  • GIF (.gif)
Limits:
  • Maximum file size: 10MB
​
purpose
string
Upload purpose (optional)Default: generation

​
Response

​
success
boolean
Whether the request succeeded
​
data
object
curl --request POST \
  --url https://toapis.com/v1/uploads/images \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@/path/to/your/image.jpg'

{
  "success": true,
  "message": "",
  "data": {
    "id": "upload_abc12345",
    "url": "https://files.toapis.com/uploads/123/1737568800_abc12345.jpg",
    "mime_type": "image/jpeg",
    "size": 89234
  }
}

​
Complete Example: Image-to-Image Workflow

Here’s a complete image-to-image workflow example:
Python Complete Example
import requests
import time

API_KEY = "your-ToAPIs-key"
BASE_URL = "https://toapis.com"

# Step 1: Upload reference image
def upload_image(file_path):
    with open(file_path, 'rb') as f:
        response = requests.post(
            f"{BASE_URL}/v1/uploads/images",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": f}
        )
    return response.json()['data']['url']

# Step 2: Create generation task
def create_generation(image_url, prompt):
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "gemini-3-pro-image-preview",
            "prompt": prompt,
            "image_urls": [{"url": image_url}],
            "size": "16:9"
        }
    )
    return response.json()['id']

# Step 3: Poll for task status
def wait_for_result(task_id):
    while True:
        response = requests.get(
            f"{BASE_URL}/v1/images/generations/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        result = response.json()
        
        if result['status'] == 'completed':
            return result['data']['url']
        elif result['status'] == 'failed':
            raise Exception(f"Generation failed: {result.get('fail_reason')}")
        
        time.sleep(2)

# Execute workflow
image_url = upload_image("reference.jpg")
print(f"✅ Image uploaded: {image_url}")

task_id = create_generation(image_url, "Transform this photo into cyberpunk style")
print(f"✅ Task created: {task_id}")

result_url = wait_for_result(task_id)
print(f"✅ Generation complete: {result_url}")