API Orkas

Documentazione API Orkas

Collega le funzionalità di chat, ricerca, voce, immagini e video di Orkas ai tuoi strumenti. Inizia da Chat per trovare l'URL di base, la chiave API e i nomi dei modelli usati dalla maggior parte delle applicazioni IA.

Crea chiave API

Chat

Usa il formato Chat Completions compatibile con OpenAI nelle applicazioni IA, negli strumenti da riga di comando o nel tuo servizio.

Impostazioni di connessione

Se un'applicazione richiede un URL di base, una chiave API e un modello, inserisci i seguenti valori.

Impostazione	Valore	Descrizione
`Base URL`	`https://orkas.ai/v1`	Usalo come indirizzo del servizio compatibile con OpenAI.
`API Key`	Crea una chiave in Account	Incolla la chiave nel campo della chiave API dell'applicazione.
`model`	`orkas-llm-1.5`Consigliato	Ideale per domande e risposte quotidiane, scrittura e lavoro d'ufficio. Include DeepSeek V4 · GPT-5.6 Luna · Claude-Sonnet-5 · Gemini-3.6 Flash.
`model`	`orkas-llm-1.5-pro`	Ideale per ricerca, video, ricerca e sviluppo e altre attività complesse. Include GPT-5.6 Sol · Claude Opus 5 · Kimi K3.

Crea un completamento di chat

Endpoint

POST

https://orkas.ai/v1/chat/completions

Crea un completamento di chat

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`model`	string	Sì	`orkas-llm-1.5` o `orkas-llm-1.5-pro`.
`messages`	array	Sì	Messaggi della conversazione. Ogni elemento contiene `role` e `content`.
`stream`	boolean	No	Restituisce una risposta in streaming quando è `true`. Valore predefinito: `false`.

Esempio di richiesta

curl https://orkas.ai/v1/chat/completions \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "orkas-llm-1.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Consumo di crediti

Voce di fatturazione	Addebito di crediti	Unità di fatturazione
`orkas-llm-1.5`	Input 20–280; lettura della cache 2–28; creazione della cache 25–350; output 120–1260	Per 1M di token; la tariffa esatta dipende dalla richiesta.
`orkas-llm-1.5-pro`	Input 140–1000; lettura della cache 14–100; creazione della cache 175–1250; output 840–4500	Per 1M di token; la tariffa esatta dipende dalla richiesta.

Ricerca

Cerca sul web e restituisce un elenco compatto di risultati pertinenti per la tua applicazione.

Cerca sul web

Endpoint

POST

https://orkas.ai/v1/search

Cerca sul web

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Testo da cercare, fino a 2000 caratteri.
`max_results`	integer	No	Numero di risultati, 1–20. Valore predefinito: `8`.

Esempio di richiesta

curl https://orkas.ai/v1/search \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"latest battery research","max_results":8}'

Consumo di crediti

Voce di fatturazione	Addebito di crediti	Unità di fatturazione
Cerca sul web	5.6	Per richiesta, fino a 20 risultati.

Voce

Trasforma il testo in un file audio. Scegli un ID voce dall'elenco qui sotto e seleziona il formato audio che ti serve.

Elenca le voci

Endpoint

GET

https://orkas.ai/v1/audio/voices

Elenca le voci

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri della richiesta

Questo endpoint non prevede parametri di richiesta.

Esempio di richiesta

curl https://orkas.ai/v1/audio/voices \
  -H "Authorization: Bearer $ORKAS_API_KEY"

ID delle voci disponibili

ID voce	Nome	Lingua
`zh_female_vv_uranus_bigtts`	vivi 2.0	Cinese / Inglese
`saturn_zh_female_cancan_tob`	知性灿灿	Cinese
`saturn_zh_female_keainvsheng_tob`	可爱女生	Cinese
`saturn_zh_female_tiaopigongzhu_tob`	调皮公主	Cinese
`saturn_zh_male_shuanglangshaonian_tob`	爽朗少年	Cinese
`saturn_zh_male_tiancaitongzhuo_tob`	天才同桌	Cinese
`zh_female_xiaohe_uranus_bigtts`	小何	Cinese
`zh_male_m191_uranus_bigtts`	云舟	Cinese
`zh_male_taocheng_uranus_bigtts`	小天	Cinese
`en_male_tim_uranus_bigtts`	Tim	Inglese
`en_female_dacey_uranus_bigtts`	Dacey	Inglese
`en_female_stokie_uranus_bigtts`	Stokie	Inglese

Genera parlato

Endpoint

POST

https://orkas.ai/v1/audio/speech

Genera parlato

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`model`	string	Sì	Usa `orkas-tts-1`.
`input`	string	Sì	Testo da sintetizzare, fino a 16384 byte UTF-8.
`voice`	string	Sì	ID voce dall'elenco qui sopra.
`language`	string	No	Lingua della narrazione, ad esempio `zh-CN` o `en`. Deve essere supportata dalla voce selezionata; in caso contrario viene usata la lingua predefinita della voce.
`response_format`	string	No	`mp3`, `wav`, `opus` o `ogg`. Valore predefinito: `mp3`.
`speed`	number	No	Velocità del parlato da 0.5 a 2.0. Valore predefinito: `1.0`.

Esempio di richiesta

curl https://orkas.ai/v1/audio/speech \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"orkas-tts-1",
    "input":"你好，欢迎使用 Orkas。",
    "voice":"zh_female_vv_uranus_bigtts",
    "language":"zh-CN",
    "response_format":"mp3",
    "speed":1.0
  }' --output speech.mp3

Consumo di crediti

Voce di fatturazione	Addebito di crediti	Unità di fatturazione
Elenca le voci	0	Per richiesta
Genera parlato	0.125	Per secondo stimato di output, arrotondato per eccesso con un minimo di un secondo.

Immagini

Genera un'immagine da una descrizione oppure fornisci immagini di riferimento per modificarle. Viene restituita un'immagine per richiesta.

Genera un'immagine

Endpoint

POST

https://orkas.ai/v1/images/generations

Genera un'immagine

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`prompt`	string	Sì	Descrizione dell'immagine, fino a 20000 caratteri.
`size`	string	No	`2k`, `3k`, `4k` o un valore larghezza×altezza supportato. Valore predefinito: `2k`.
`response_format`	string	No	`url` o `b64_json`. Valore predefinito: `b64_json`.
`reference_images`	array	No	Fino a quattro URL HTTPS o URL di dati immagine supportati per la modifica.
`async`	boolean	No	Restituisce un ID attività quando è `true`. Consigliato per evitare il timeout delle richieste. Valore predefinito: `false`.

Esempio di richiesta

curl https://orkas.ai/v1/images/generations \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"A product photo on a clean studio background",
    "size":"2k",
    "response_format":"url",
    "async":true
  }'

Per le richieste più lunghe: imposta "async": true. L'API restituisce un id attività; usa l'URL di stato finché il risultato non è pronto.

Controlla lo stato della generazione

Endpoint

GET

https://orkas.ai/v1/images/generations/{id}

Controlla lo stato della generazione

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del percorso

Parametro	Tipo	Obbligatorio	Descrizione
`id`	string	Sì	ID dell'attività restituito dalla richiesta di creazione.

Esempio di richiesta

curl https://orkas.ai/v1/images/generations/$TASK_ID \
  -H "Authorization: Bearer $ORKAS_API_KEY"

Consumo di crediti

Voce di fatturazione	Addebito di crediti	Unità di fatturazione
Genera un'immagine	22	Per immagine generata
Controlla lo stato della generazione	0	Per richiesta

Video

Crea un video a partire da testo o contenuti multimediali di riferimento. Le richieste video vengono eseguite in modo asincrono: usa l'ID attività restituito per controllare l'avanzamento.

Crea un video

Endpoint

POST

https://orkas.ai/v1/videos

Crea un video

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`prompt`	string	Sì	Descrizione del video da generare o modificare.
`duration`	integer	No	4–15 secondi. Valore predefinito: `5`.
`resolution`	string	No	`480p`, `720p` o `1080p`. Valore predefinito: `720p`.
`quality`	string	No	`balanced` bilancia velocità e consumo di crediti; `quality` dà priorità alla qualità e alla stabilità della generazione. Valore predefinito: `balanced`. Orkas continua a selezionare automaticamente il modello video compatibile.
`ratio`	string	No	`16:9`, `9:16`, `1:1`, `4:3`, `3:4` o `21:9`. Valore predefinito: `16:9`.
`generate_audio`	boolean	No	Genera l'audio del video. Valore predefinito: `true`.
`reference_image_urls`	array	No	Fino a nove URL HTTPS pubblici di immagini.
`reference_video_urls`	array	No	Fino a tre URL HTTPS pubblici di video.
`operation`	string	No	`generate` o `edit`. La modifica richiede almeno un video di riferimento. Valore predefinito: `generate`.
`seed`	integer	No	Seed facoltativo per una generazione ripetibile.

Esempio di richiesta

curl https://orkas.ai/v1/videos \
  -H "Authorization: Bearer $ORKAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"Camera circles a ceramic lamp in a dark studio",
    "duration":5,
    "resolution":"720p",
    "quality":"balanced",
    "ratio":"16:9",
    "generate_audio":true
  }'

Controlla lo stato del video

Endpoint

GET

https://orkas.ai/v1/videos/{id}

Controlla lo stato del video

Autenticazione

Authorization: Bearer $ORKAS_API_KEY

Parametri del percorso

Parametro	Tipo	Obbligatorio	Descrizione
`id`	string	Sì	ID dell'attività restituito dalla richiesta di creazione.

Esempio di richiesta

curl https://orkas.ai/v1/videos/$TASK_ID \
  -H "Authorization: Bearer $ORKAS_API_KEY"

Consumo di crediti

Voce di fatturazione	Addebito di crediti	Unità di fatturazione
`balanced` · Da testo o immagine a video · 480p	37	Per secondo di output
`balanced` · Da testo o immagine a video · 720p	80	Per secondo di output
`balanced` · Da testo o immagine a video · 1080p	248	Per secondo di output
`quality` · Da testo o immagine a video · 480p	46	Per secondo di output
`quality` · Da testo o immagine a video · 720p	100	Per secondo di output
`quality` · Da testo o immagine a video · 1080p	248	Per secondo di output
`balanced` / `quality` · Modifica video o generazione da video di riferimento · 480p	51	Per secondo di output
`balanced` / `quality` · Modifica video o generazione da video di riferimento · 720p	109	Per secondo di output
`balanced` / `quality` · Modifica video o generazione da video di riferimento · 1080p	271	Per secondo di output
Controlla lo stato del video	0	Per richiesta

Sicurezza e limiti

Mantieni riservate le chiavi API, usa chiavi separate per applicazioni diverse ed elimina immediatamente una chiave se potrebbe essere stata esposta.

Invia la chiave nell'intestazione della richiesta Authorization: Bearer sk-orkas-….
Per raggruppare il consumo di crediti di una conversazione, invia lo stesso ID opaco in X-Orkas-Conversation-Id nelle relative richieste. Usa solo lettere, cifre, - o _ (fino a 64 caratteri); non inviare un titolo o il contenuto dei messaggi.
Non inserire una chiave nel codice eseguito nel browser o nelle app mobili, negli URL, nei log o nei sistemi di controllo del codice sorgente.
Crea una chiave separata per ogni applicazione, così da poterla sostituire senza influire sugli altri servizi.
Limiti per chiave: 120 richieste/min per chat e ricerca, 60 per il parlato, 30 richieste di immagini e 10 richieste video. I controlli di stato consentono 120 richieste/min.
Se le richieste sono troppo frequenti, l'API restituisce HTTP 429. Attendi qualche istante prima di riprovare.

Cronologia dei crediti

L'utilizzo dell'API è contrassegnato separatamente nella cronologia dei crediti di Orkas Web, così puoi distinguerlo dall'utilizzo in Orkas.