Upload images to StableStudio for editing or image-to-video workflows, paid via USDC micropayment ($0.01).
What it does
The `/api/upload` endpoint is part of StableStudio, a pay-per-generation AI image and video platform that accepts USDC micropayments on Base (or Tempo L2) with no API keys or subscriptions. This specific endpoint handles the first step of a three-step file upload flow: you POST a JSON body with `filename` and `contentType`, pay $0.01 via a signed USDC payment header, and receive back an `uploadId` plus a `clientToken` for direct upload to Vercel Blob storage. After uploading the file to Vercel Blob (step 2), you confirm the upload at `/api/upload/confirm` (step 3, authenticated via SIGN-IN-WITH-X wallet signature, no additional payment). The resulting `blobUrl` can then be used as input to any of StableStudio's edit or image-to-video endpoints.
StableStudio supports a wide range of models for downstream use of uploaded images: Nano Banana Pro and GPT Image 1.5 for image editing, Flux 2 Pro and Grok for image editing, and Seedance, Wan 2.6, Sora 2, Veo 3.1, and Grok Video for image-to-video generation. Accepted content types are JPEG, PNG, GIF, and WebP. The endpoint accepts both x402 and MPP (Tempo method, charge intent) payment protocols. The upload endpoint is POST-only; HEAD and GET return 405, which is expected behavior for this route.
Capabilities
Use cases
- —Upload a reference image before running an image edit with Nano Banana Pro, GPT Image 1.5, Flux 2 Pro, or Grok
- —Upload a first-frame image for image-to-video generation with Seedance, Wan 2.6, Sora 2, or Veo 3.1
- —Upload style reference images for Veo 3.1 reference mode
- —Upload interpolation frames (first + last) for Veo 3.1 or Seedance interpolation
Fit
Best for
- —Agents that need to programmatically upload images before calling StableStudio edit/i2v endpoints
- —Workflows combining image upload with pay-per-call AI generation
- —Automated pipelines that need keyless, wallet-authenticated file staging
Not for
- —Standalone file hosting — uploaded blobs are scoped to StableStudio workflows
- —Large file or non-image uploads (only JPEG, PNG, GIF, WebP accepted)
- —Users who only need text-to-image or text-to-video (no upload needed)
Quick start
# Step 1: Request upload token (requires PAYMENT-SIGNATURE header with signed USDC auth)
curl -X POST https://stablestudio.dev/api/upload \
-H 'Content-Type: application/json' \
-H 'PAYMENT-SIGNATURE: <signed-usdc-payment>' \
-d '{"filename": "photo.png", "contentType": "image/png"}'Example
Request
{
"filename": "photo.png",
"contentType": "image/png"
}Response
{
"pathname": "uploads/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.png",
"uploadId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"expiresAt": "2025-01-15T12:30:00.000Z",
"clientToken": "vercel_blob_rw_abc123..."
}Endpoint
Quality
Full OpenAPI schema with detailed request/response documentation, clear pricing ($0.01 fixed), complete three-step upload flow documented in x-guidance, and dual protocol support (x402 + MPP). The endpoint returned 405 on HEAD/GET probes, which is expected since it's POST-only. The 200 response schema is not fully specified in the OpenAPI (just "Successful response"), but the guidance docs describe the response shape in detail.
Warnings
- —Probe returned 405 on HEAD and GET — this is expected since /api/upload is POST-only; the endpoint is live
- —The OpenAPI 200 response for /api/upload lacks a formal JSON schema; response shape is documented only in the x-guidance text
- —Upload is only step 1 of 3; agents must also call Vercel Blob PUT and /api/upload/confirm to complete the flow
Citations
- —Upload endpoint costs $0.01 (fixed price)https://stablestudio.dev/api/openapi.json
- —Accepted content types: image/jpeg, image/jpg, image/png, image/gif, image/webphttps://stablestudio.dev/api/openapi.json
- —Three-step upload flow: get token, upload to Vercel Blob, confirmhttps://stablestudio.dev/api/openapi.json
- —Payment via USDC on Base (eip155:8453) or Tempo L2https://stablestudio.dev/api/openapi.json
- —Supports both x402 and MPP (method: tempo, intent: charge) protocolshttps://stablestudio.dev/api/openapi.json