StableStudio

# StableStudio API > AI image/video generation via micropayments. USDC on Base, Solana, or Tempo. No API keys. Base URL: `https://stablestudio.dev` ## Recommended Defaults - **Image generation:** `nano-banana-pro` - Best quality/cost ratio, supports up to 4K resolution - **Video generation:** `veo-3.1` - Best quality/cost ratio, supports up to 1080p resolution ## Payment Flow 1. `POST /api/generate/{model}/{operation}` without payment header - Returns `402` with `PAYMENT-REQUIRED` header (base64 JSON) 2. Decode requirements, sign USDC authorization, POST with `PAYMENT-SIGNATURE` header - Returns `200` with `{jobId, status:"pending"}` and `PAYMENT-RESPONSE` header 3. Poll `GET /api/jobs/{jobId}` with `SIGN-IN-WITH-X` header until complete ## 402 Response Format Response body is empty `{}`. Requirements in header: ``` PAYMENT-REQUIRED: <base64> ``` Decoded: ```json { "x402Version": 2, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "39000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xfbd7b7Ed48146aD9bEfF956212c77cE056815ad0" }], "resource": { "url": "https://stablestudio.dev/api/generate/nano-banana/generate", "description": "Nano Banana - generate" } } ``` `amount` is USDC micro-units (6 decimals). 39000 = $0.039. ## Routes | Endpoint | Cost | Time | |----------|------|------| | `/api/generate/nano-banana/generate` | $0.039 | ~5s | | `/api/generate/nano-banana/edit` | $0.039 | ~5s | | `/api/generate/nano-banana-pro/generate` | $0.13-0.24 | ~10s | | `/api/generate/nano-banana-pro/edit` | $0.13-0.24 | ~10s | | `/api/generate/grok/generate` | $0.07 | ~3s | | `/api/generate/grok/edit` | $0.022 | ~3s | | `/api/generate/grok-video/generate` | $0.15-0.75 | ~17s | | `/api/generate/gpt-image-1/generate` | $0.011-0.25 | ~10s | | `/api/generate/gpt-image-1/edit` | $0.011-0.25 | ~10s | | `/api/generate/gpt-image-1.5/generate` | $0.009-0.20 | ~3s | | `/api/generate/gpt-image-1.5/edit` | $0.009-0.20 | ~3s | | `/api/generate/flux-2-pro/generate` | $0.05-0.06 | ~5s | | `/api/generate/flux-2-pro/edit` | $0.05-0.06 | ~5s | | `/api/generate/seedance/t2v` | $0.33-0.99 | ~1min | | `/api/generate/seedance/i2v` | $0.33-0.99 | ~1min | | `/api/generate/seedance-fast/t2v` | $0.04-0.12 | ~40s | | `/api/generate/seedance-fast/i2v` | $0.04-0.12 | ~40s | | `/api/generate/wan-2.6/t2v` | $0.34-1.02 | 2-5min | | `/api/generate/wan-2.6/i2v` | $0.34-1.02 | 2-5min | | `/api/generate/sora-2/generate` | $0.40-1.20 | 1-3min | | `/api/generate/sora-2-pro/generate` | $3.00-12.50 | 2-5min | | `/api/generate/veo-3.1/generate` | $1.60-3.20 | 1-2min | | `/api/generate/veo-3.1-fast/generate` | $0.40-0.80 | ~30s | | `/api/upload` | $0.01 | instant | ## Input Schemas **Image generation:** ```json {"prompt": "string", "aspectRatio": "1:1|16:9|9:16"} ``` **Image editing** (requires upload first): ```json {"prompt": "string", "images": ["https://blob-url..."]} ``` - `gpt-image` edit adds `input_fidelity: "high"|"low"` (default: high) - `nano-banana-pro` edit supports up to 14 images **nano-banana-pro** (adds resolution): ```json {"prompt": "string", "aspectRatio": "...", "imageSize": "1K|2K|4K"} ``` **grok** (13 aspect ratios including ultra-wide): ```json {"prompt": "string", "aspect_ratio": "1:1|16:9|9:16|4:3|3:4|3:2|2:3|2:1|1:2|19.5:9|9:19.5|20:9|9:20"} ``` **grok edit** (requires upload first): ```json {"prompt": "string", "images": ["https://blob-url..."], "aspect_ratio": "...same as above"} ``` **grok-video:** ```json {"prompt": "string", "duration": "3|6|9|12|15", "resolution": "480p|720p", "aspect_ratio": "1:1|16:9|9:16|4:3|3:4|3:2|2:3"} ``` **grok-video i2v** (with image): ```json {"prompt": "string", "image": "https://blob-url...", "duration": "3|6|9|12|15", "resolution": "480p|720p"} ``` **gpt-image** (adds quality): ```json {"prompt": "string", "quality": "low|medium|high", "size": "1024x1024|1536x1024|1024x1536"} ``` **flux-2-pro:** ```json {"prompt": "string", "aspect_ratio": "1:1|16:9|9:16|3:2|2:3|4:5|5:4|4:3|3:4", "resolution": "0.5 MP|1 MP|2 MP"} ``` **flux-2-pro edit** (requires upload first): ```json {"prompt": "string", "images": ["https://blob-url..."], "aspect_ratio": "...same as above", "resolution": "0.5 MP|1 MP|2 MP"} ``` **seedance/t2v:** ```json {"prompt": "string", "duration": "4|5|6|7|8|9|10|11|12", "resolution": "480p|720p|1080p", "aspect_ratio": "16:9|9:16|4:3|3:4|1:1|21:9", "generate_audio": false, "camera_fixed": false} ``` **seedance/i2v:** ```json {"prompt": "string", "image": "https://blob-url...", "duration": "4|5|6|7|8|9|10|11|12", "resolution": "480p|720p|1080p", "aspect_ratio": "16:9|9:16|4:3|3:4|1:1|21:9"} ``` **seedance-fast** uses same schemas as seedance but at lower cost. **wan-2.6/t2v:** ```json {"prompt": "string", "duration": "5|10|15", "size": "1280*720|720*1280|1920*1080|1080*1920", "enablePromptExpansion": true, "multiShots": false} ``` **wan-2.6/i2v:** ```json {"prompt": "string", "image": "https://blob-url...", "duration": "5|10|15", "resolution": "720p|1080p", "enablePromptExpansion": true, "multiShots": false} ``` **sora-2:** ```json {"prompt": "string", "seconds": "4|8|12", "size": "1280x720|720x1280"} ``` **sora-2-pro:** ```json {"prompt": "string", "seconds": "10|15|25", "size": "1280x720|720x1280|1792x1024|1024x1792"} ``` **veo-3.1:** ```json {"prompt": "string", "durationSeconds": "4|6|8", "aspectRatio": "16:9|9:16"} ``` **veo-3.1 interpolation** (animate between frames): ```json {"prompt": "string", "image": "https://first...", "lastFrame": "https://last..."} ``` ## File Upload Upload images for editing or image-to-video. Three-step flow: **Step 1: Get upload token** (payment, $0.01) ``` POST /api/upload PAYMENT-SIGNATURE: <signed payment> Content-Type: application/json {"filename": "image.png", "contentType": "image/png"} ``` Returns: ```json {"uploadId": "uuid", "clientToken": "vercel_blob_...", "pathname": "uploads/uuid/image.png", "expiresAt": "..."} ``` **Step 2: Upload file directly to Vercel Blob** ```bash curl -X PUT "https://vercel.com/api/blob/?pathname=uploads/uuid/image.png" \ -H "authorization: Bearer $clientToken" \ -H "x-content-type: image/png" \ -H "x-api-version: 11" \ --data-binary @image.png ``` Returns `{"url": "https://....blob.vercel-storage.com/..."}`. **Step 3: Confirm upload** (SIGN-IN-WITH-X auth, no payment) ``` POST /api/upload/confirm SIGN-IN-WITH-X: <base64> Content-Type: application/json {"uploadId": "uuid", "blobUrl": "https://....blob.vercel-storage.com/..."} ``` Returns `{"success": true, "upload": {"id": "...", "blobUrl": "..."}}`. Use the `blobUrl` in edit/i2v requests. ## Job Polling (SIGN-IN-WITH-X) Job routes require wallet signature authentication (no payment): ``` GET /api/jobs/{jobId} SIGN-IN-WITH-X: <base64> ``` Header contains base64-encoded CAIP-122 message: ```json { "domain": "stablestudio.dev", "address": "0x...", "uri": "https://stablestudio.dev/api/jobs/{jobId}", "version": "1", "chainId": "eip155:8453", "nonce": "<random>", "issuedAt": "<ISO8601>", "expirationTime": "<ISO8601>", "signature": "0x..." } ``` If auth missing/invalid, returns 402 with SIWX extension: ```json { "x402Version": 2, "accepts": [], "extensions": { "sign-in-with-x": { "info": { "domain": "stablestudio.dev", "uri": "https://stablestudio.dev/api/jobs/{jobId}", "version": "1", "nonce": "<server-generated>", "issuedAt": "<ISO8601>", "expirationTime": "<ISO8601>" }, "supportedChains": [{ "chainId": "eip155:8453", "type": "eip191" }], "schema": { "..." : "..." } } } } ``` **Routes:** - `GET /api/jobs/{jobId}` - Get job status - `GET /api/jobs` - List jobs (`?limit=20&status=complete`) - `DELETE /api/jobs/{jobId}` - Delete failed job **Response:** ```json {"status": "complete", "result": {"imageUrl": "https://..."}} ``` Videos return `{videoUrl, thumbnailUrl}`. **Polling intervals:** Images every 3s (2min timeout), Videos every 10s (10min timeout)