Embedding، تصویر و صدا

Embeddings (بردار معنایی)#

متن را به بردار عددی تبدیل می‌کند؛ پایهٔ جستجوی معنایی، RAG، خوشه‌بندی و پیشنهاددهی. مدل‌های فعلی: openai/text-embedding-3-small، openai/text-embedding-3-large و gemini/gemini-embedding-2.

resp = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["هوش مصنوعی چیست؟", "یادگیری ماشین شاخه‌ای از هوش مصنوعی است."],
)
vectors = [d.embedding for d in resp.data]
print(len(vectors), len(vectors[0]))  # 2 1536

پاسخ همان قالب OpenAI است:

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, ...] }],
  "model": "openai/text-embedding-3-small",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}

نمونهٔ کامل جستجوی معنایی و RAG را در نمونه‌ها ببین.

ساخت تصویر#

یک endpoint برای همهٔ مدل‌های تصویری: GPT Image (OpenAI)، Gemini Flash Image، Grok Imagine، FLUX (BFL و Together) و Stable Image. خروجی همیشه به‌صورت b64_json (PNG) برمی‌گردد؛ پس لینک موقتی نداری که منقضی شود.

import base64

resp = client.images.generate(
    model="openai/gpt-image-2",
    prompt="A fluffy cream Persian robot cat with a teal headset, soft 3D, studio light",
    size="1536x1024",
    quality="high",
)
open("cat.png", "wb").write(base64.b64decode(resp.data[0].b64_json))

{
  "created": 1791590400,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "revised_prompt": "..." }],
  "usage": { "prompt_tokens": 38, "completion_tokens": 4160, "total_tokens": 4198, "prompt_tokens_details": { "cached_tokens": 0 } }
}

تبدیل متن به صدا (TTS)#

متن را به فایل صوتی MP3 تبدیل می‌کند. با مدل‌های OpenAI (مثل openai/gpt-4o-mini-tts) یا ElevenLabs (مثل elevenlabs/eleven_v4 با بهترین کیفیت فارسی). پاسخ مستقیماً بایت‌های صوتی با Content-Type: audio/mpeg است.

with client.audio.speech.with_streaming_response.create(
    model="openai/gpt-4o-mini-tts",
    voice="coral",
    input="سلام! به هوشی خوش اومدی. امروز چطور می‌تونم کمکت کنم؟",
    instructions="گرم، صمیمی و با سرعت متوسط",
) as resp:
    resp.stream_to_file("welcome.mp3")

هزینهٔ TTS بر اساس هر ۱۰۰۰ کاراکتر متن ورودی محاسبه می‌شود. برای قابلیت‌های پیشرفتهٔ ElevenLabs (استریم، timestamp، دیالوگ چندگوینده، تغییر صدا، افکت و موسیقی) از API بومی ElevenLabs استفاده کن.

تبدیل صدا به متن (STT)#

فایل صوتی (mp3، wav، m4a، webm، ogg و…) تا ۵۰ مگابایت را به متن تبدیل می‌کند. مدل‌ها: openai/gpt-transcribe (پیش‌فرض)، openai/gpt-4o-transcribe، groq/whisper-large-v3 (سریع و ارزان) و elevenlabs/scribe_v2 (با زمان‌بندی کلمه‌به‌کلمه).

with open("meeting.m4a", "rb") as f:
    tr = client.audio.transcriptions.create(model="openai/gpt-transcribe", file=f, language="fa")
print(tr.text)

{
  "text": "سلام، جلسهٔ امروز دربارهٔ برنامهٔ فصل بعد است...",
  "language": "fa",
  "duration": 312.4,
  "words": [{ "text": "سلام", "start": 0.12, "end": 0.48 }, ...]
}

ساخت ویدیو (ناهمگام)#

ساخت ویدیو از متن با gemini/veo-3.1-generate-preview (ویدیو با صدای هم‌زمان) و xai/grok-imagine-video-1.5. ساخت ویدیو چند دقیقه طول می‌کشد؛ برای همین پاسخ فوراً با وضعیت in_progress برمی‌گردد و باید با GET /v1/videos/{id} وضعیت را هر ۵ تا ۱۰ ثانیه بررسی کنی. هزینه (به ازای هر ثانیه ویدیو) فقط وقتی کسر می‌شود که ویدیو تحویل شود؛ اگر ساخت ناموفق باشد، چیزی کسر نمی‌شود.

import time, requests

H = {"Authorization": f"Bearer {HOOSHI_API_KEY}"}
job = requests.post("https://api.hooshi.ai/v1/videos", headers=H, json={
    "model": "xai/grok-imagine-video-1.5",
    "prompt": "نمای هوایی آرام از کوه دماوند هنگام طلوع",
    "duration": 8,
}).json()

while job["status"] == "in_progress":
    time.sleep(8)
    job = requests.get(f"https://api.hooshi.ai/v1/videos/{job['id']}", headers=H).json()

if job["status"] == "completed":
    open("video.mp4", "wb").write(requests.get(job["url"], headers=H).content)

{
  "id": "9f1c6f0e-...",
  "object": "video",
  "model": "xai/grok-imagine-video-1.5",
  "status": "completed",
  "seconds": 8,
  "aspect_ratio": "16:9",
  "url": "https://api.hooshi.ai/v1/videos/9f1c6f0e-.../content",
  "hooshi": { "cost": 104328, "currency": "IRT" }
}

مقادیر status: in_progress، completed و failed (همراه error.message). فایل ویدیو با همان کلید API از آدرس url دانلود می‌شود.

خطاهای اعتبارسنجی#

اگر فیلد الزامی (مثل prompt، input، voice یا file) را نفرستی یا از سقف مجاز بیشتر باشد، پاسخ 422 با قالب اعتبارسنجی برمی‌گردد:

{
  "message": "The voice field is required.",
  "errors": { "voice": ["The voice field is required."] }
}