Phosor
Browse documentationImport Image

POST /api/v1/storage/image/import

API version: v1.2.4

Import a reference image from a remote URL, then use it with MiniMax H3 Standard or Turbo image-to-video. Importing and generating are separate requests.

Endpoint

Plain text
POST /api/v1/storage/image/import

Authentication

Required. Include your API key in the request header:

Plain text
X-API-Key: your-api-key-here

Request Body

Content Type

Plain text
application/json

Parameters

ParameterTypeRequiredDescription
urlstringYesPublic URL to image file (JPEG, PNG, or WebP)
filenamestringNoOverride filename (defaults to filename from URL)

URL Requirements

  • Protocol: Use HTTPS. HTTP is also supported.
  • Ports: Standard ports only (80 for HTTP, 443 for HTTPS)
  • No credentials: URLs must not contain authentication credentials
  • Public access: URLs must be publicly accessible
  • File format: Must point to .jpg, .jpeg, .png, or .webp files
  • Published default size limit: 20 mebibytes (20,971,520 bytes); active account or service limits can differ. See upload limitations.

Security Validation

The API performs SSRF protection:

  • DNS resolution validated against private/reserved IP ranges
  • Loopback addresses blocked (127.0.0.0/8, ::1)
  • Private networks blocked (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
  • AWS metadata endpoint blocked (169.254.169.254)
  • Link-local addresses blocked

Response

Success (200 OK)

JSON
{
  "file_id": "img-550e8400-e29b-41d4-a716-446655440000",
  "s3_url": "https://bucket.s3.amazonaws.com/images/img-550e8400.jpg",
  "s3_key": "images/img-550e8400-e29b-41d4-a716-446655440000.jpg",
  "filename": "my-image.jpg",
  "message": "Image imported successfully. Use the s3_key as image_url in inference/submit."
}

Response Fields

FieldTypeDescription
file_idstringUnique identifier for the uploaded image
s3_urlstringFull Storage URL of the stored image
s3_keystringStorage key to use as image_url in inference/submit
filenamestringStored filename
messagestringSuccess message with usage instructions

Examples

Import Image (cURL)

cURL
curl -X POST https://phosor.ai/api/v1/storage/image/import \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/photos/my-image.jpg"
  }'

Import and Use for I2V (Python)

Python
import requests

API_KEY = "your-api-key"
BASE_URL = "https://phosor.ai"
MODEL_ID = "minimax/h3/image-to-video"
# For Turbo, use "minimax/h3/image-to-video/turbo".

# Step 1: Import image from URL
import_response = requests.post(
    f"{BASE_URL}/api/v1/storage/image/import",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com/photos/my-image.jpg"
    },
    timeout=60
)
import_response.raise_for_status()
image_data = import_response.json()
print(f"Image imported: {image_data['file_id']}")

# Step 2: Use the s3_key for Image-to-Video generation
submit_response = requests.post(
    f"{BASE_URL}/api/v1/inference/submit",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A cinematic scene with gentle camera movement",
        "model": MODEL_ID,
        "image_url": image_data["s3_key"],
        "duration": 5,
        "resolution_tier": "480p",
        "aspect_ratio": "16:9"
    },
    timeout=60
)
submit_response.raise_for_status()
print(f"Job submitted: {submit_response.json()['request_id']}")

JavaScript Example

JavaScript
async function importImageAndGenerate(imageUrl, apiKey, modelId = 'minimax/h3/image-to-video') {
  // Pass 'minimax/h3/image-to-video/turbo' as modelId for Turbo.
  // Step 1: Import image
  const importRes = await fetch('https://phosor.ai/api/v1/storage/image/import', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: imageUrl })
  });
  if (!importRes.ok) throw new Error(`Image import failed: ${importRes.status}`);
  const imageData = await importRes.json();
  console.log('Image imported:', imageData.file_id);

  // Step 2: Submit I2V job
  const submitRes = await fetch('https://phosor.ai/api/v1/inference/submit', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'A cinematic scene with gentle camera movement',
      model: modelId,
      image_url: imageData.s3_key,
      duration: 5,
      resolution_tier: '480p',
      aspect_ratio: '16:9'
    })
  });
  if (!submitRes.ok) throw new Error(`Video submission failed: ${submitRes.status}`);
  const job = await submitRes.json();
  console.log('Job submitted:', job.request_id);
}

Error Responses

Invalid Image Format (400 Bad Request)

JSON
{
  "error": "Invalid image format",
  "message": "URL must point to an image file (.jpg, .jpeg, .png, .webp)"
}

SSRF Protection (400 Bad Request)

JSON
{
  "error": "Request failed",
  "message": "URL resolves to a disallowed IP range"
}

Invalid Port (400 Bad Request)

JSON
{
  "error": "Request failed",
  "message": "URL port is not allowed"
}

Unauthorized (401 Unauthorized)

Use a valid API key in X-API-Key; see the common API contract.

For H3 generation dimensions and reference requirements, see video generation limits. After submission, check request status and retrieve the result with the returned request_id. Compare H3 Standard and Turbo.