PicassoIA API की मदद से आप PicassoIA के इमेज और वीडियो मॉडल अपने ख़ुद के कोड से चला सकते हैं:

1. आप किसी मॉडल के लिए एक प्रेडिक्शन बनाते हैं।
2. प्रेडिक्शन पूरा होने तक आप उसे पोल करते हैं।
3. आप आउटपुट URL पढ़ते हैं।

• बेस URL: https://api.picassoia.com/v1
• फ़ॉर्मेट: JSON रिक्वेस्ट और रिस्पॉन्स, UTF-8।
• कीमत: API प्रेडिक्शन फ़िलहाल मुफ़्त हैं। इनमें कोई क्रेडिट खर्च नहीं होता।
• कौन इस्तेमाल कर सकता है: Infinite प्लान वाले अकाउंट।

विषय-सूची

• प्रमाणीकरण
• त्वरित शुरुआत
• मॉडल
• एंडपॉइंट
• प्रेडिक्शन ऑब्जेक्ट
• पोलिंग और ETA
• रद्द करना
• त्रुटियाँ
• सीमाएँ

प्रमाणीकरण

हर रिक्वेस्ट के Authorization हेडर में एक API key होनी चाहिए:

Authorization: Bearer pia_sk_…

• API key बनाना। picassoia.com पर अपने अकाउंट के API keys सेक्शन में जाकर keys बनाएँ।
  • पूरी key सिर्फ़ एक बार दिखाई जाती है, जब आप उसे बनाते हैं। उसे किसी सुरक्षित जगह पर सहेज लें।
  • एक अकाउंट में एक समय पर 2 keys हो सकती हैं। नई key के लिए जगह बनानी हो, तो उनमें से एक को रिवोक करें।
• API key रिवोक करना। रिवोक की गई key तुरंत काम करना बंद कर देती है।
• API keys सिर्फ़ सर्वर पर रखें। जिसके पास भी आपकी key है, वह आपके अकाउंट पर प्रेडिक्शन चला सकता है, इसलिए key कभी भी किसी वेब पेज या मोबाइल ऐप में न डालें। API कोई CORS हेडर नहीं भेजता, इसलिए ब्राउज़र इसे सीधे कॉल नहीं कर सकते।
• प्लान में बदलाव। आपका प्लान बदलने पर भी keys बनी रहती हैं। Infinite प्लान के बिना प्रेडिक्शन बनाने की रिक्वेस्ट का जवाब 403 plan_required होता है। अपने प्रेडिक्शन पढ़ना, उनकी सूची देखना और उन्हें रद्द करना पहले की तरह काम करता रहता है।

त्वरित शुरुआत

1. एक प्रेडिक्शन बनाएँ:

curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions \
  -H "Authorization: Bearer $PICASSOIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "a lighthouse at sunset, oil painting", "aspect_ratio": "16:9"}}'

जवाब (201 Created) starting स्टेट में एक प्रेडिक्शन होता है:

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "model": "picassoia/picassoia-image",
  "input": {
    "prompt": "a lighthouse at sunset, oil painting",
    "aspect_ratio": "16:9",
    "num_outputs": 1,
    "output_format": "jpg",
    "output_quality": 80
  },
  "output": null,
  "error": null,
  "status": "starting",
  "created_at": "2026-10-01T09:30:00.000Z",
  "started_at": null,
  "completed_at": null,
  "metrics": { "predict_time": null },
  "urls": {
    "get": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
    "cancel": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60/cancel"
  },
  "eta": { "seconds": 12, "next_poll_in_seconds": 6 }
}

2. इसे पोल करें (हर कॉल के बीच eta.next_poll_in_seconds सेकंड रुकें), जब तक status succeeded, failed या canceled न हो जाए:

curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
  -H "Authorization: Bearer $PICASSOIA_API_KEY"

3. आउटपुट पढ़ें:

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "status": "succeeded",
  "output": ["https://…/lighthouse.jpg"],
  "metrics": { "predict_time": 6.4 },
  "eta": null
}

(बाकी फ़ील्ड यहाँ नहीं दिखाए गए हैं।)

Node.js (fetch)

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_API_KEY}`,
  'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))

async function run(model, input) {
  const created = await fetch(`${API}/models/${model}/predictions`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ input }),
  })
  let prediction = await created.json()
  if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)

  while (!['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
    await sleep(prediction.eta?.next_poll_in_seconds ?? 2)
    prediction = await (await fetch(prediction.urls.get, { headers })).json()
  }
  if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
  return prediction.output
}

const video = await run('picassoia/seedance-2.5-lite', {
  prompt: 'a paper boat sailing down a rainy street',
  duration: 5,
})
console.log(video) // "https://…/video.mp4"

Python (requests)

import os, time, requests

API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}

def run(model, input):
    response = requests.post(f"{API}/models/{model}/predictions", json={"input": input}, headers=HEADERS)
    prediction = response.json()
    if not response.ok:
        raise RuntimeError(f"{prediction['code']}: {prediction['detail']}")
    while prediction["status"] not in ("succeeded", "failed", "canceled"):
        time.sleep((prediction.get("eta") or {}).get("next_poll_in_seconds", 2))
        prediction = requests.get(prediction["urls"]["get"], headers=HEADERS).json()
    if prediction["status"] != "succeeded":
        raise RuntimeError(prediction["error"] or prediction["status"])
    return prediction["output"]

images = run("picassoia/picassoia-image-editor-pro", {
    "prompt": "put the cat from image 1 on the sofa from image 2",
    "images": ["https://example.com/cat.png", "https://example.com/sofa.jpg"],
})
print(images)  # ["https://…/result.webp"]

मॉडल

हर मॉडल का सटीक स्कीमा JSON Schema के रूप में भी उपलब्ध है: GET /v1/models/{owner}/{name} input_schema (हर फ़ील्ड, उसकी सीमाओं और डिफ़ॉल्ट वैल्यू के साथ) और output_schema लौटाता है।

इनपुट के रूप में इमेज। इमेज फ़ील्ड में इन दोनों में से किसी भी तरह की वैल्यू दी जा सकती है:

• एक https URL, जिस तक सार्वजनिक रूप से पहुँचा जा सके;
• एक data URL: data:image/png;base64,…, या image/jpeg या image/webp भी, हर एक अधिकतम 5 MB का।

इमेज PNG, JPEG या WebP होनी चाहिए। PicassoIA हर इमेज की अपनी एक कॉपी सहेजता है, इसलिए प्रेडिक्शन के input में उसी कॉपी का URL दिखता है। कुछ सौ KB से बड़ी किसी भी फ़ाइल के लिए URL इस्तेमाल करें: पूरी रिक्वेस्ट बॉडी की सीमा 10 MB है।

अज्ञात फ़ील्ड अस्वीकार कर दिए जाते हैं, ताकि टाइपिंग की कोई गलती चुपचाप डिफ़ॉल्ट वैल्यू में न बदल जाए। जवाब 422 invalid_input होता है।

picassoia/picassoia-image

आउटपुट: 1 या 2 इमेज URL की सूची।

picassoia/picassoia-image-editor-pro

आउटपुट: 1 या 2 इमेज URL की सूची।

picassoia/picassoia-video

आउटपुट: एक MP4 URL (एक string)।

picassoia/seedance-2.5-lite

आउटपुट: एक MP4 URL (एक string)।

एंडपॉइंट

मॉडल ऑब्जेक्ट

{
  "id": "picassoia/seedance-2.5-lite",
  "owner": "picassoia",
  "name": "seedance-2.5-lite",
  "title": "Seedance 2.5 Lite",
  "description": "Text or image to video with synchronized audio: …",
  "input_schema": { "type": "object", "properties": { "…": {} }, "required": ["prompt"], "additionalProperties": false },
  "output_schema": { "type": "string", "format": "uri" }
}

प्रेडिक्शन बनाना

POST /v1/models/{owner}/{name}/predictions, बॉडी { "input": { … } } के साथ।

• मॉडल के जॉब स्वीकार करते ही API जवाब देता है, आमतौर पर कुछ ही सेकंड में, और उस समय प्रेडिक्शन starting स्टेट में होता है। API कभी भी नतीजे का इंतज़ार नहीं करता।
• अगर प्रेडिक्शन तुरंत फ़ेल हो जाता है, तब भी जवाब 201 ही होता है, जिसमें प्रेडिक्शन failed स्टेट में और अपने error के साथ होता है। उदाहरण के लिए, ऐसा तब होता है जब सेफ़्टी फ़िल्टर इनपुट को अस्वीकार कर देता है।
• अगर कोई प्रेडिक्शन नहीं बना, तो जवाब एक त्रुटि होता है: अमान्य इनपुट, ज़रूरी प्लान न होना, एक साथ प्रगति में बहुत ज़्यादा प्रेडिक्शन, सेवा उपलब्ध न होना।

प्रेडिक्शन की सूची

GET /v1/predictions आपकी सभी keys से बने API प्रेडिक्शन लौटाता है, हर पेज पर 50, सबसे नए पहले।

• next अगले पेज का URL (…/v1/predictions?cursor=…) होता है, या आख़िरी पेज पर null।
• previous हमेशा null होता है।
• picassoia.com पर आपके डिलीट किए गए प्रेडिक्शन इसमें शामिल नहीं होते।

कोई भी प्रेडिक्शन आपकी किसी भी key से देखा जा सकता है, लेकिन किसी और को वह कभी नहीं दिखता।

प्रेडिक्शन ऑब्जेक्ट

स्टेटस।

starting और processing के बीच का फ़र्क एक अनुमान है, जो प्रेडिक्शन बनते समय कतार में उसकी जगह के आधार पर लगाया जाता है। नया प्रेडिक्शन हमेशा starting होता है। आख़िरी तीन स्टेटस अंतिम हैं: इनमें से किसी एक में पहुँचा प्रेडिक्शन फिर कभी नहीं बदलता।

फ़ेल हुए प्रेडिक्शन की त्रुटियाँ। फ़ेल हुए प्रेडिक्शन का error इनमें से कोई एक मैसेज होता है:

• सेफ़्टी फ़िल्टर ने इनपुट या आउटपुट को अस्वीकार कर दिया। मैसेज (SAFETY_CHECKER_PICASSO_FILTER_S4) पर ख़त्म होता है।
• The prediction failed. You can try again.
• The prediction timed out. You can try again. 3 घंटे के भीतर यह पूरा नहीं हुआ।

आउटपुट। आउटपुट URL PicassoIA पर होस्ट किए जाते हैं। जिन फ़ाइलों को आप रखना चाहते हैं, उन्हें डाउनलोड कर लें।

पोलिंग और ETA

eta.next_poll_in_seconds बताता है कि अगला पोल कब करना फ़ायदेमंद है:

1. अनुमानित समय के आधे पर।
2. जब अनुमानित समय पूरा हो जाए।
3. उसके बाद हर 2 सेकंड में।

उदाहरण के लिए, अगर अनुमान 10 सेकंड का है: 5 सेकंड बाद पोल करें, फिर 10 सेकंड बाद, फिर हर 2 सेकंड में। इससे ज़्यादा तेज़ी से पोल करने पर नतीजा जल्दी नहीं मिलता।

रद्द करना

POST /v1/predictions/{id}/cancel:

रद्द किया गया प्रेडिक्शन आपके एक साथ प्रगति में रहने वाले 5 प्रेडिक्शन में अपनी जगह तुरंत खाली कर देता है।

त्रुटियाँ

त्रुटियाँ JSON problem details के रूप में आती हैं, और साथ में प्रोग्राम के लिए एक स्थिर code भी होता है:

{
  "title": "Too many predictions in progress",
  "detail": "This account can have up to 5 predictions queued or running at once, shared by its API keys and MCP connections, and 5 are. Wait for one to finish and try again.",
  "status": 429,
  "code": "concurrency_limit",
  "retry_after": 10,
  "limit": 5,
  "running": 5
}

invalid_fields। 422 जवाब में हर गलत फ़ील्ड की सूची होती है:

{
  "title": "Input validation failed",
  "status": 422,
  "code": "invalid_input",
  "detail": "input.duration: At 720p the longest clip is 10 seconds.",
  "invalid_fields": [
    { "type": "invalid_value", "field": "input.duration", "description": "At 720p the longest clip is 10 seconds." }
  ]
}

सीमाएँ