Metin

Mesaj Oluştur

Anthropic Messages API formatını kullanarak bir mesaj oluşturur

POST
/v1/messages

Genel Bakış

Bu uç nokta, yerel Anthropic Messages formatını kabul eder; bu sayede Anthropic SDK'ları ve bunlar üzerine inşa edilmiş araçlar TokenLab temel URL'si ile çalışır. accepted_request_formats kısmında anthropic_messages listelenen modellerle (Claude modelleri ve diğer bazı modeller) çalışır.

messages alanı user ve assistant sıralarını tutar. Sistem talimatlarını en üst düzeydeki system alanına yerleştirin. max_tokens zorunludur. system veya tool gibi rollere sahip OpenAI tarzı mesajlar için Chat Completions kısmını kullanın.

Anthropic SDK için temel URL: https://api.tokenlab.sh (/v1 soneki olmadan)

İstek Başlıkları (Request Headers)

x-api-keystringheader

TokenLab API anahtarınız. x-api-key veya Authorization: Bearer <API_KEY> gönderin. Her ikisini de farklı değerlerle gönderirseniz, TokenLab x-api-key değerini kullanır.

anthropic-versionstringheader

Anthropic API sürümü. Anthropic SDK'ları bunu sizin yerinize gönderir; API'yi doğrudan çağırdığınızda 2023-06-01 kullanın.

anthropic-betastringheader

Virgülle ayrılmış Anthropic beta özellik adları. TokenLab başlığı iletir; bir beta özelliğinin çalışıp çalışmadığı modele bağlıdır. file_id referansı veren içerikler files-api-2025-04-14 gerektirir.

İstek Gövdesi (Request Body)

Desteklenen isteğe bağlı parametreler, kabul edilen değerler ve varsayılanlar seçilen modele bağlıdır. Örnekleme (sampling), mantık yürütme (reasoning) veya araç seçeneklerini ayarlamadan önce model detaylarını kontrol edin.

modelstringzorunlu

anthropic_messages formatını destekleyen bir modelin kimliği. Mevcut yetenekler için model detaylarını kontrol edin.

messagesarrayzorunlu

role (user veya assistant) ve content içeren mesaj nesneleri dizisi. 100.000 mesaja kadar desteklenir.

content düz bir metin veya içerik bloklarından oluşan bir dizi olabilir. Görsel göndermek için, görsel URL'lerini veya Base64 dizelerini doğrudan düz metin içine yerleştirmek yerine yapılandırılmış içerik bloklarını kullanın. tool_use, tool_result, thinking ve document gibi diğer yerel bloklar, bunları destekleyen modeller için kabul edilir.

Örnek içerik blokları:

  • metin bloğu: { "type": "text", "text": "Bu görseli tanımla" }
  • URL ile görsel bloğu: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • Base64 ile görsel bloğu: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensintegerzorunlu

Oluşturulacak maksimum token sayısı. Zorunludur: TokenLab varsayılan bir değer eklemez. Kullanılabilir maksimum değer modele bağlıdır; model detaylarındaki max_output_tokens kısmına bakın. Büyük bir değer, istek çalışırken TokenLab'in bakiyenizden tuttuğu miktarı artırır ve tutarı karşılayamayan bir bakiye 402 hatası döndürür.

systemstring | array

messages dizisinden ayrı olarak, metin veya metin içerik bloklarından oluşan bir dizi olarak sistem istemi (system prompt).

temperaturenumber

Örnekleme sıcaklığı. Destek, izin verilen değerler ve varsayılan değer seçilen modele bağlıdır; varsayılanı kullanmak için bu alanı boş bırakın.

streambooleanvarsayılan: false

Yanıtı sunucu tarafından gönderilen olaylar (server-sent events) akışı olarak döndürür. Bkz: Akış (Streaming).

thinkingobject

Yerel düşünme (thinking) yapılandırması, örneğin {"type":"enabled","budget_tokens":10000}. Desteklenen modlar, bütçeler ve diğer parametrelerle kombinasyonlar seçilen modele bağlıdır. Manuel bütçeyi reddettiği bilinen bir model için TokenLab, {"type":"enabled"} değerini uyarlanabilir düşünme olarak çalıştırır ve budget_tokens değerini yok sayar.

toolsarray

Model için kullanılabilir araçlar. Destek seçilen modele bağlıdır.

tool_choiceobject

Yerel araç seçimi nesnesi, örneğin {"type":"auto"}. Desteklenen türler seçilen modele bağlıdır.

cache_controlobject

İstem önbelleğe alma (prompt-caching) işareti, örneğin {"type":"ephemeral"}; bir saatlik önbellek için "ttl": "1h" ekleyin. En üst düzeyde otomatik önbelleğe almayı açar. Ayrıca system bloklarında, tools içinde ve içerik bloklarında da ayarlayabilirsiniz. Destek modele bağlıdır; destekleyen modeller capabilities kısmında prompt-cache listeler.

top_pnumber

Nucleus örnekleme parametresi. Sıcaklık veya top_p'den birini kullanın, ikisini birden kullanmayın. Destek seçilen modele bağlıdır.

top_kinteger

Her token için yalnızca en iyi K seçenekten örnekleme yapın. Destek seçilen modele bağlıdır.

stop_sequencesarray

Modelin oluşturmayı durdurmasına neden olacak özel durdurma dizileri. 8.191 girişe kadar desteklenir.

metadataobject

Anthropic formatında istek meta verileri. user_id, son kullanıcınız için opak bir tanımlayıcıdır.

service_tierstring

Yalnızca auto ve standard_only etkilidir. TokenLab yalnızca standart katmanı fiyatlandırır ve diğer tüm değerleri yok sayar.

Yanıt (Response)

idstring

Benzersiz mesaj tanımlayıcısı.

typestring

Her zaman message.

rolestring

Her zaman assistant.

contentarray

text, thinking veya tool_use gibi içerik bloklarından oluşan dizi.

modelstring

Yanıtı üreten model.

stop_reasonstring

Oluşturmanın durma nedeni; end_turn, max_tokens, stop_sequence veya tool_use gibi. Model, refusal gibi başka değerler de döndürebilir.

stop_sequencestring | null

Oluşturmayı sonlandıran durdurma dizisi veya null.

usageobject

input_tokens ve output_tokens ile token kullanımı. Model istem önbelleği (prompt-cache) token'larını bildirdiğinde, usage ayrıca cache_creation_input_tokens ve cache_read_input_tokens değerlerini de içerir.

Her yanıt, request-id ve X-Request-ID başlıklarında istek kimliğini taşır. Destek ekibiyle iletişime geçtiğinizde bunu belirtin.

İstek

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Yanıt

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

Görsel Giriş Örneği

Görsel desteğine sahip Claude modelleri için görselleri messages[].content içine yapılandırılmış görsel blokları olarak yerleştirin.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Please describe this image."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Gelişmiş Düşünme (Extended Thinking) Örneği

reasoning yeteneğine sahip bir model kullanın. max_tokens ve budget_tokens değerlerini modelin sınırlarına göre ayarlayın; bazı modeller farklı bir düşünme yapılandırmasına ihtiyaç duyar.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "Solve this math problem..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

Akış (Streaming)

Anthropic sunucu tarafından gönderilen olayları (SSE) almak için "stream": true olarak ayarlayın: message_start, content_block_start, content_block_delta, content_block_stop, message_delta ve message_stop. Token kullanımı message_start ve message_delta içinde gelir.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Tell me a story"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • Model çalışırken, akış : keep-alive gibi SSE yorum satırları taşıyabilir. SDK'lar bunları yok sayar.
  • Bir hata oluştuğunda HTTP durumu zaten 200 olabilir. Akış başladıktan sonra oluşan bir hata, aşağıdakiyle aynı hata gövdesine sahip bir event: error olayı olarak gelir.

Hatalar (Errors)

Hatalar Anthropic hata formatını kullanır. request_id, TokenLab istek kimliğidir. Bazı hatalar code ve hint gibi alanlar ekler.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: Required. /v1/messages follows the native Anthropic contract and does not infer a default max_tokens value."
  },
  "request_id": "req_01JEXAMPLE"
}
Durumerror.typeTipik neden
400invalid_request_errorEksik veya geçersiz bir alan, bilinmeyen bir model veya Messages formatını kabul etmeyen bir model
401authentication_errorAPI anahtarı eksik veya geçersiz
402billing_errorBakiye isteği karşılayamıyor (error.code değeri insufficient_balance). Harcama limitine ulaşan bir API anahtarı da 402 alır; error.code quota_exceeded ve error.type rate_limit_error olur
403permission_errorAPI anahtarı istenen modeli kullanamıyor veya hesap askıya alınmış ya da kısıtlanmış
409conflict_errorAynı Idempotency-Key ile yeniden deneme. Bkz: Idempotency key ile güvenli yeniden deneme
413request_too_largeİstek girdisi çok büyük
429rate_limit_errorÇok fazla istek
500, 502, 503api_error veya overloaded_errorİstek tamamlanamadı veya şu anda bunun için bir rota mevcut değil. Daha sonra tekrar deneyin
504timeout_errorİstek zaman aşımına uğradı

İlgili arayüzler

Yetkilendirme

BearerAuth
AuthorizationBearer <token>

API Anahtarı kimlik doğrulaması. API anahtarlarını Dashboard > API > API Keys bölümünden oluşturun veya yönetin.

Konum: header

Başlıklar

X-TokenLab-Delivery-Policy?string

İstek bazlı Teslimat politikası. API anahtarı ve Çalışma Alanı varsayılanlarını geçersiz kılar. Otomatik olarak önce TokenLab Verified dener ve çıktı, istek kabulü veya kalıcı kaynak oluşturma öncesinde bir kez Official seçeneğine geçiş yapabilir.

Geçerli değerler

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Aynı isteğin ikinci kez çalıştırılmasını engelleyen isteğe bağlı anahtar. Her istek için UUID gibi yeni ve benzersiz bir değer gönderin ve zaman aşımı sonrası yeniden denemeler için bu değeri koruyun. Aynı anahtarla yapılan bir yeniden deneme tekrar çalışmaz: idempotency_replay_unavailable ile 409 hatası veya gövde değiştiğinde genellikle idempotency_conflict hatası döndürür. İstisna: Akış dışı (non-stream) bir sonuç istemci bağlantısı kesildikten sonra tamamlandığında, 24 saat içinde aynı anahtar ve gövde ile yapılan bir yeniden deneme, Idempotent-Replayed: true başlığıyla ve ikinci bir ücretlendirme olmaksızın o sonucu (1 MB'a kadar) döndürür. 255 karakterden uzun bir anahtar yok sayılır ve bu durumda isteğin idempotency koruması olmaz. Bkz: Idempotency anahtarı ile güvenli yeniden deneme.

Uzunluk1 <= length <= 255

İstek gövdesi

application/json

Yanıt

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json