Console API

Autenticazione

Ogni richiesta ha bisogno di una chiave API nell'header Authorization: Authorization: Bearer fk_live_.... Le chiavi si creano qui sotto e vengono mostrate una sola volta, alla creazione: conserva la tua in un posto sicuro.

La tua chiave API

Modelli

Scegli un modello con il campo model. I prezzi sono per immagine, in Fellowi Coins, e sono esattamente quelli dell'Image Studio web. Il text-to-image è ciò che ottieni con una lista images vuota; se invii dei riferimenti parte invece il modello di editing, che può costare una cifra diversa.

Se ometti model ottieni fellowi-text-to-image - lo stesso modello, allo stesso prezzo, che ha sempre avuto un'integrazione scritta prima che esistesse questa scelta.

curl https://fellowi.com/api/v1/api/models

Crea un'immagine

POST /v1/api/images restituisce subito 202 con una generazione in coda; l'immagine vera e propria richiede fino a qualche minuto. Invia un header Idempotency-Key così un nuovo tentativo non paga mai due volte.

images è facoltativo: fino a 10 URL pubblici di immagini da cui il modello parte per modificare (una foto di un compagno, un tuo riferimento). Ognuna aggiunge 10 monete al prezzo, e una lista non vuota usa il modello di editing al posto del text-to-image.

curl -X POST https://fellowi.com/api/v1/api/images \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "a neon-lit cyberpunk portrait",
    "model": "fellowi-text-to-image",
    "quality": "standard",
    "format": "png",
    "aspectRatio": "1:1",
    "enhancePrompt": false,
    "enhanceStyle": "default",
    "images": []
  }'

Opzioni della richiesta

Tutto ciò che segue è facoltativo. Ogni valore predefinito è il comportamento che l'API aveva prima che quell'opzione esistesse, quindi un'integrazione più vecchia continua a funzionare senza modifiche.

quality

standard o high. Imposta la risoluzione e il prezzo - vedi la tabella qui sopra.

format

png o jpeg. Il valore predefinito è png.

aspectRatio

auto (il valore predefinito) oppure uno tra 1:1, 3:4, 4:3, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9, 9:21.

enhancePrompt / enhanceStyle

Imposta enhancePrompt su true per far riscrivere il prompt prima del rendering, per 10 monete in più. enhanceStyle orienta quella riscrittura: default, artistic, photographic, technical, anime o realistic. Viene ignorato quando enhancePrompt è disattivato.

images

Fino a 10 URL di immagini raggiungibili pubblicamente da cui partire per modificare. Se ne invii anche solo una, la richiesta passa al modello di editing. Ogni immagine di riferimento in images aggiunge 10 monete.

Controlla il risultato

Fai polling su GET /v1/api/images/{id} finché status è succeeded, poi scarica imageUrl. Le generazioni failed vengono rimborsate in automatico.

curl https://fellowi.com/api/v1/api/images/{id} \
  -H "Authorization: Bearer fk_live_..."

Quando una generazione fallisce

Una generazione fallita rimborsa le sue monete e segnala uno di quattro codici in failureCode: TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR o UNKNOWN. Non viene pubblicato nulla di più specifico - un codice interno ti direbbe qualcosa sulla nostra pipeline, non sulla tua richiesta.

Limiti di frequenza e costi

Ogni chiave ha un proprio limite di richieste al minuto (lo vedi nel pannello qui sotto) e può avere un tetto giornaliero di monete. Sono protezioni contro gli abusi, non il vero limite: ciò che davvero decide quante immagini puoi generare è il saldo dei tuoi Fellowi Coins. 403 con una pagina HTML: la richiesta è stata fermata prima di arrivare all'API, di solito a causa del suo User-Agent. Quello predefinito di Python-urllib è bloccato, quindi mandane uno tuo, per esempio User-Agent: my-app/1.0.