وبسرویس گیسو همان قالب API شرکت OpenAI را دارد. اگر پیش از این با SDK رسمی OpenAI کار کردهاید، چیز تازهای لازم نیست یاد بگیرید:
نشانی پایه (base URL) را https://gisoo.pro/api/v1 میگذارید، کلید گیسو را جای کلید OpenAI میدهید و همان کد اجرا میشود.
این صفحه شما را از صفر تا اولین پاسخ مدل میبرد.
پیش از شروع
- یک حساب گیسو. اگر در نِت اَرز حساب دارید، با همان وارد شوید؛ حساب، اعتبار و کلیدها در هر دو یکی است.
- اعتبار در حساب. شارژ از ۵۰٬۰۰۰ سکه شروع میشود و اشتراک ماهانه ندارد. تا ۲ دلار مصرف، احراز هویت لازم نیست؛ برای بیشتر از آن، یک بار هویتتان را در اپ تأیید کنید.
- یک محیط اجرا: ترمینال با curl، یا پایتون ۳.۸ به بالا، یا Node.js ۱۸ به بالا، یا هر زبانی که درخواست HTTP بفرستد. سرور یا هاست داخل ایران هم کافی است و فیلترشکن نمیخواهد (آزمایش اتصال از سرور).
چهار قدم تا اولین پاسخ
-
وارد اپ گیسو شوید
از gisoo.pro/app با شمارهٔ موبایل و کد پیامکی وارد شوید. شمارهٔ تازه همانجا حساب باز میکند.
-
حساب را شارژ کنید
در بخش اعتبار مبلغ را انتخاب کنید و در درگاه بانکی نِت اَرز بپردازید. اعتبار به دلار در حسابتان مینشیند و هزینهٔ هر درخواست از همین اعتبار کم میشود.
-
یک کلید دسترسی (API Key) بسازید
در بخش API یک پروژه و برایش یک کلید بسازید. کلید با
sk-gisoo-v1-شروع میشود و فقط یک بار نشان داده میشود؛ همان لحظه جایی امن نگهش دارید. -
اولین درخواست را بفرستید
کلید را در متغیر محیطی
GISOO_API_KEYبگذارید و یکی از نمونههای پایین را اجرا کنید.
کلید را در متغیر محیطی بگذارید
کلید را مستقیم در کد ننویسید؛ کدی که در گیت یا دست همکار میرود، کلید را هم با خودش میبرد. متغیر محیطی سادهترین راه است:
# Linux / macOS
export GISOO_API_KEY="sk-gisoo-v1-..."
# Windows PowerShell
$env:GISOO_API_KEY = "sk-gisoo-v1-..."
اولین درخواست
این نمونه یک پیام به مدل gpt-4o-mini میفرستد؛ مدلی ارزان و سریع که برای آزمایش مناسب است. زبان را از زبانهها انتخاب کنید؛ انتخابتان برای همهٔ نمونههای مستندات میماند.
برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید هماناند.
curl https://gisoo.pro/api/v1/chat/completions \
-H "Authorization: Bearer $GISOO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "system", "content": "Answer in Persian, in two sentences."},
{"role": "user", "content": "What is an API key?"}
]
}'
# pip install openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://gisoo.pro/api/v1",
api_key=os.environ["GISOO_API_KEY"],
)
reply = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Answer in Persian, in two sentences."},
{"role": "user", "content": "What is an API key?"},
],
)
print(reply.choices[0].message.content)
print(reply.usage) # tokens this request used
// npm install openai
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://gisoo.pro/api/v1",
apiKey: process.env.GISOO_API_KEY,
});
const reply = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [
{ role: "system", content: "Answer in Persian, in two sentences." },
{ role: "user", content: "What is an API key?" },
],
});
console.log(reply.choices[0].message.content);
<?php
// composer require openai-php/client
require 'vendor/autoload.php';
$client = OpenAI::factory()
->withBaseUri('https://gisoo.pro/api/v1')
->withApiKey(getenv('GISOO_API_KEY'))
->make();
$reply = $client->chat()->create([
'model' => 'gpt-4o-mini',
'messages' => [
['role' => 'system', 'content' => 'Answer in Persian, in two sentences.'],
['role' => 'user', 'content' => 'What is an API key?'],
],
]);
echo $reply->choices[0]->message->content;
// go get github.com/openai/openai-go
package main
import (
"context"
"fmt"
"os"
"github.com/openai/openai-go"
"github.com/openai/openai-go/option"
)
func main() {
client := openai.NewClient(
option.WithBaseURL("https://gisoo.pro/api/v1/"),
option.WithAPIKey(os.Getenv("GISOO_API_KEY")),
)
reply, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
Model: "gpt-4o-mini",
Messages: []openai.ChatCompletionMessageParamUnion{
openai.SystemMessage("Answer in Persian, in two sentences."),
openai.UserMessage("What is an API key?"),
},
})
if err != nil {
panic(err)
}
fmt.Println(reply.Choices[0].Message.Content)
}
// dotnet add package OpenAI
using System.ClientModel;
using OpenAI;
using OpenAI.Chat;
var client = new ChatClient(
model: "gpt-4o-mini",
credential: new ApiKeyCredential(Environment.GetEnvironmentVariable("GISOO_API_KEY")!),
options: new OpenAIClientOptions { Endpoint = new Uri("https://gisoo.pro/api/v1") });
ChatCompletion reply = client.CompleteChat(
new SystemChatMessage("Answer in Persian, in two sentences."),
new UserChatMessage("What is an API key?"));
Console.WriteLine(reply.Content[0].Text);
پاسخ همان شکلی را دارد که از OpenAI میگیرید:
{
"id": "req_4b1f0c9a7e2d8f3a6c5b0e1d",
"object": "chat.completion",
"created": 1790000000,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "…" },
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 29, "completion_tokens": 64, "total_tokens": 93 }
}
choices[0].message.contentمتن پاسخ مدل است.usageتعداد توکن ورودی و خروجی را میگوید؛ هزینهٔ درخواست از همین حساب میشود.idشناسهٔ درخواست در گیسوست. همین مقدار در هدرX-Request-Idهم میآید و با GET /requests/{id} هزینهٔ دقیق همان درخواست را میدهد.
فقط مقدار model را عوض کنید: openrouter/anthropic/claude-sonnet-4.5 برای Claude، gemini-3.6-flash برای Gemini یا deepseek-v4-flash برای DeepSeek. بقیهٔ کد همان میماند. فهرست کامل را در مدلها و انتخاب مدل ببینید.
اگر جواب نگرفتید
| پاسخ | یعنی چه | چه کنید |
|---|---|---|
401 missing_api_key | کلید به درخواست نرسید. | هدر Authorization: Bearer … را بفرستید و مطمئن شوید متغیر محیطی در همان ترمینال تنظیم شده است. |
401 invalid_api_key | کلید درست نیست. | کلید را دوباره و کامل کپی کنید؛ فاصله یا خط تازه در ابتدا و انتهایش نماند. |
402 insufficient_credit | اعتبار برای این درخواست کافی نیست. | حساب را شارژ کنید یا max_tokens را کمتر بگذارید تا مبلغ کمتری کنار گذاشته شود. |
403 kyc_required | سقف مصرف پیش از احراز هویت پر شده است. | احراز هویت را در اپ گیسو کامل کنید. |
404 model_not_found | شناسهٔ مدل را پیدا نکردیم. | شناسه را از GET /models یا صفحهٔ مدلها بردارید. |
فهرست کامل در صفحهٔ خطاها آمده است.
قدم بعدی
پاسخ پرسشتان را پیدا نکردید؟
شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.