API Referansı
Grok Imagine Segment Haritası
Asenkron bir Görev oluşturmak için segment haritası uç noktasını kullanın.
01
Genel Bakış
Segment haritası uç noktasını desteklenen bir modelle kullanın. Durumunu almak için döndürülen Görev Kimliğini kullanın veya aşağıda belgelenen teslimler için callback_url sağlayın.
Hızlı başlangıç
- Bir API anahtarı oluşturun ve RUNAPI_API_KEY olarak ayarlayın.
- Desteklenen bir model seçin ve gövdesi o modelin şemasıyla eşleşen bir POST isteği gönderin.
- Döndürülen görev kimliğini saklayın, ardından bir terminal durumuna ulaşana kadar yoklama yapın ya da aşağıda belgelenen geri çağırmaları işleyin.
Uç Nokta
- Temel URL
https://runapi.ai- API sürümü
v1- Kimlik doğrulama
Authorization: Bearer YOUR_API_TOKEN
02
Desteklenen modeller
Güncel fiyatlandırma, hız sınırları ve ticari kullanım ayrıntıları için bir model sayfası açın.
03
JSON gövdesiİstek şeması
Alanlar ve izin verilen değerler seçili modele göre değişir. Sağlandığında, callback_url aşağıda belgelenen Görev teslimatlarını alır.
grok-imagine-image-2-04 alan
callback_urlstring
İsteğe bağlı
Terminal Görev teslimi için webhook URL'si.
image_urlstring
İsteğe bağlı
Hizmetin getirebileceği genel görsel URL'si.
modelstring
Zorunlu
Model tanımlayıcısı.
source_task_idstring
İsteğe bağlı
Aynı hesaba ait tamamlanmış Image 2.0 metinden görüntüye Görev kimliği. Uyumluluk girdisi; bunun yerine image_url kullanın.
Koşullu kurallar
Bu gereksinimler, listelenen tüm koşulların eşleştiği durumlarda uygulanır.
-
Şu durumlarda
- Gerekli
- Kabul edilmez
-
Şu durumlarda
image_url = {"present" => true}- Gerekli
- Kabul edilmez
source_task_id
-
Şu durumlarda
source_task_id = {"present" => true}- Gerekli
- Kabul edilmez
image_url
04
HTTP 202Kabul oluştur
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200Yoklama işleniyor
GET /api/v1/grok_imagine/segment_map/:id
Yanıt şeması
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200Yoklama tamamlandı
GET /api/v1/grok_imagine/segment_map/:id
Yanıt şeması
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"segments": {
"items": {
"properties": {
"index": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"segments",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"segments": [
{
"index": 1,
"name": "subject",
"url": "https://file.runapi.ai/reference-segment.png"
}
],
"status": "completed"
}07
HTTP 200Yoklama başarısız oldu
GET /api/v1/grok_imagine/segment_map/:id
Yanıt şeması
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200Müşteri geri çağırması: tamamlandı
POST callback_url
Yanıt şeması
JSON
{
"properties": {
"id": {
"type": "string"
},
"segments": {
"items": {
"properties": {
"index": {
"type": "integer"
},
"name": {
"type": "string"
},
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"segments"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"id": "tsk_reference_demo",
"segments": [
{
"index": 1,
"name": "subject",
"url": "https://file.runapi.ai/reference-segment.png"
}
],
"status": "completed"
}09
HTTP 200Müşteri geri çağırması: başarısız oldu
POST callback_url
Yanıt şeması
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "Authentication required"
}11
HTTP 401Hatalar
GET /api/v1/grok_imagine/segment_map/:id
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "Authentication required"
}12
HTTP 400Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir doğrulama özeti.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Herkese açık istek alanına göre anahtarlanan doğrulama mesajları; her alan için insan tarafından okunabilir dizelerden oluşan bir dizi içerir.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}Yanıt örneği
JSON
{
"error": "model must be one of: grok-imagine-image-2-0"
}13
HTTP 402Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "Insufficient balance"
}14
HTTP 429Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504Hatalar
POST /api/v1/grok_imagine/segment_map
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "The request timed out"
}19
HTTP 404Hatalar
GET /api/v1/grok_imagine/segment_map/:id
Yanıt şeması
JSON
{
"properties": {
"error": {
"description": "İnsan tarafından okunabilir hata mesajı.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Yanıt örneği
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
Oluşturulan Kod Örnekleri
Doğrudan cURL kullanın veya diliniz için bir SDK yükleyin. Her örnek, bu başvuruda gösterilen doğrulanmış isteği gönderir.
Yükle
Shell
pip install runapi-grok-imagine
PYTHON
import os
from runapi.grok_imagine import GrokImagineClient
client = GrokImagineClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.segment_map.create(
model="grok-imagine-image-2-0",
image_url="https://cdn.runapi.ai/public/samples/image.jpg"
)