Developer Reference

API Documentation

Programmatic access to the USD Refinery. Convert 3D assets, retrieve health reports, and integrate into your pipeline.

Quick Start

1
Get an API key from the pricing page
2Add the key to your requests via X-API-Key header
3Upload a file, poll for completion, download the result
# Convert a file
curl -X POST https://converter.inside-media.com/api/v1/convert \
  -H "X-API-Key: im_your_key_here" \
  -F "file=@model.obj"

# Poll status
curl https://converter.inside-media.com/api/v1/status/{job_id} \
  -H "X-API-Key: im_your_key_here"

# Download result
curl -o result.zip https://converter.inside-media.com/api/v1/download/{job_id} \
  -H "X-API-Key: im_your_key_here"

Authentication

All API endpoints require an API key. Pass it via the X-API-Key header (recommended) or the ?api_key= query parameter.

Keys are prefixed with im_ and tied to a tier (Starter, Pro, or Enterprise) that determines your rate limits and max file size.

Starter
50 / mo · 25 MB max
Pro
500 / mo · 100 MB max
Enterprise
5,000 / mo · 500 MB max

Supported Formats

Input
OBJGLBGLTFSTLPLY3MFDAEUSDUSDAUSDC
Output
USDZUSDCUSDAGLB

Endpoints

POST/api/v1/convert

Convert a file

Upload a 3D asset and convert it to USD/USDZ. Conversion runs asynchronously — poll the status endpoint or use a webhook.

Parameters
filemultipartrequiredThe 3D file to convert
export_formatstringOutput format: usdz (default), usdc, usda, glb
y_upbooleanForce Y-up orientation (default: true)
root_xformbooleanApply root transform fix (default: true)
webhook_urlstringURL to POST when conversion completes
Example
curl -X POST https://converter.inside-media.com/api/v1/convert \
  -H "X-API-Key: im_your_key_here" \
  -F "file=@model.obj" \
  -F "export_format=usdz"
Response
{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "filename": "model.obj",
  "export_format": "usdz",
  "status_url": "/api/v1/status/a1b2c3d4-...",
  "health_url": "/api/v1/health/a1b2c3d4-...",
  "download_url": "/api/v1/download/a1b2c3d4-..."
}
GET/api/v1/status/{job_id}

Poll job status

Check the current status of a conversion job. Poll until status is 'completed' or 'failed'.

Example
curl https://converter.inside-media.com/api/v1/status/a1b2c3d4-... \
  -H "X-API-Key: im_your_key_here"
Response
{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "filename": "model.obj",
  "export_format": "usdz",
  "created_at": 1710000000.0,
  "completed_at": 1710000005.0,
  "health_score": 87,
  "engine_readiness": {
    "unreal": true,
    "houdini": true,
    "apple_ar": true,
    "web_threejs": true
  }
}
GET/api/v1/health/{job_id}

Get health report

Retrieve the full health/lint report for a completed conversion. Returns JSON by default, or a downloadable PDF.

Parameters
formatstringjson (default) or pdf
Example
# JSON report
curl https://converter.inside-media.com/api/v1/health/a1b2c3d4-... \
  -H "X-API-Key: im_your_key_here"

# PDF report
curl -o report.pdf \
  "https://converter.inside-media.com/api/v1/health/a1b2c3d4-...?format=pdf" \
  -H "X-API-Key: im_your_key_here"
Response
{
  "health_score": 87,
  "fixes_applied": ["normals_regenerated", "root_xform_applied"],
  "lod_variants": 3,
  "collision_meshes_generated": true,
  "physics_material_inferred": "metal",
  "engine_readiness": { ... },
  "geometry": {
    "vertices": 12450,
    "triangles": 24800,
    "meshes": 3
  }
}
GET/api/v1/download/{job_id}

Download result

Download the converted asset as a ZIP bundle containing the USD file(s), health report JSON, and metadata.

Example
curl -o result.zip \
  https://converter.inside-media.com/api/v1/download/a1b2c3d4-... \
  -H "X-API-Key: im_your_key_here"
Response
Binary ZIP file containing:
• converted asset (USDZ/USDC/USDA/GLB)
• health_report.json
• metadata.json
GET/api/v1/jobs

List jobs

List your recent conversion jobs with status and health scores.

Parameters
limitintegerResults per page (default: 20)
offsetintegerPagination offset (default: 0)
Example
curl "https://converter.inside-media.com/api/v1/jobs?limit=10" \
  -H "X-API-Key: im_your_key_here"
Response
{
  "jobs": [
    {
      "job_id": "a1b2c3d4-...",
      "status": "completed",
      "filename": "model.obj",
      "export_format": "usdz",
      "created_at": 1710000000.0,
      "health_score": 87
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}
POST/api/v1/batch

Batch convert

Convert multiple files in a single request (max 20). Each file counts against your monthly quota. Files that fail validation are rejected individually.

Parameters
filesmultipart[]requiredMultiple 3D files to convert
export_formatstringOutput format for all files (default: usdz)
y_upbooleanForce Y-up orientation (default: true)
root_xformbooleanApply root transform fix (default: true)
webhook_urlstringURL to POST when each conversion completes
Example
curl -X POST https://converter.inside-media.com/api/v1/batch \
  -H "X-API-Key: im_your_key_here" \
  -F "files=@chair.obj" \
  -F "files=@table.glb" \
  -F "files=@lamp.stl" \
  -F "export_format=usdz"
Response
{
  "batch_size": 3,
  "accepted": 3,
  "rejected": 0,
  "jobs": [
    { "job_id": "...", "status": "pending", "filename": "chair.obj", ... },
    { "job_id": "...", "status": "pending", "filename": "table.glb", ... },
    { "job_id": "...", "status": "pending", "filename": "lamp.stl", ... }
  ]
}

Error Codes

401Missing or invalid API key
403API key revoked or inactive
404Job not found
413File exceeds tier size limit
429Monthly conversion limit reached
400Unsupported format or invalid request
202Conversion still in progress (poll again)

Webhooks

Pass a webhook_url when submitting a conversion. When the job completes (or fails), we'll POST the full job status to your URL.

This is ideal for CI/CD pipelines where you don't want to poll. Combine with the download endpoint to automatically retrieve converted assets.

# Your webhook receives:
POST https://your-server.com/webhook
Content-Type: application/json

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "health_score": 87,
  "download_url": "/api/v1/download/a1b2c3d4-..."
}
Get an API Key→