Skip to main content
POST
Text-to-image: generate images from a text prompt
右側のインタラクティブな Playground では、エンドポイントを直接テストできます。Authorization に APIキーを入力し(形式: Bearer sk-xxx)、prompt を入力して、aspect_ratio / resolution を選び、送信してください。
このページを使うタイミング: prompt だけからの画像生成です。画像のアップロードは不要です。既存の画像を編集したり、複数を融合したりするには、画像編集エンドポイント を使用してください。
⚠️ このエンドポイントに参照画像を送信しないでくださいここで image / image_url / images を渡しても エラーは発生しません。200 を返して、prompt から新しい画像を生成します — 参照は黙って破棄され、それでも課金されますエラーのシグナルがないため、通常は出力が入力とまったく関係ないと誰かが気づいたときに初めて表面化します。参照画像を使うワークフローでは必ず /v1/images/edits を使用してください。
⚠️ 無効なパラメータではエラーは発生しません無効な aspect_ratio(例: 5:7)、resolution(例: 1K1024x1024)および response_format(例: base64)はすべて 黙ってデフォルトにフォールバック し、それでも画像を返します。出力が期待どおりでない場合は、まずパラメータのスペルを確認してください — resolution の値は小文字の 1k / 2k である点に注意してください。1つ例外があります: resolution: "4k"503 model_service_unavailable を返し、これは ティアが未対応 という意味であって、チャネルが停止しているという意味ではありません。再試行しても解決しません。
すべての画像 API は 同期的 です。非同期のタスク ID はないため、クライアントが切断されると、リクエストがまだ課金中であっても結果を失います。1K は約 9 秒、2K は約 15-17 秒かかるため、クライアントのタイムアウトを 360 秒に設定してください画像 API のベストプラクティス を参照してください。

コード例

Python (OpenAI SDK)

Python (生の requests)

cURL

Node.js (ネイティブ fetch)

ブラウザー JavaScript

パラメータリファレンス

アスペクト比ごとの実際の出力ピクセル数:
seed はサポートされていません(エラーなく受け付けられますが、効果はありません — 結果は再現できません)。マスクによる inpainting もサポートされていません。size / quality / style のような OpenAI 形式のフィールドは、黙って無視されます。

レスポンス形式

レスポンスフィールドの注意点
  • data[] エントリには、response_format に応じて url または b64_json のどちらか一方が含まれます — 両方が含まれることはありません。
  • revised_prompt は返されずrespect_moderation / model も返されません。存在すると想定しないでください。
  • b64_jsondata:image/...;base64, プレフィックスのない生の base64 です — そのままデコードしてください。
  • created は常に 0 であり、タイムスタンプとしては使用できません。
  • n > 1 では、data 配列に複数のエントリが入ります — data[0] だけを読まないでください。
usage は照合には使用できません: prompt_tokens は実際の prompt の長さにかかわらず常に 1000 x n です。このシリーズは画像ごとの定額料金($0.02 / $0.045)で課金されます。実際の請求額は APIYI Console の課金記録を参照してください。

承認

Authorization
string
header
必須

API Key created in the APIYI Console

ボディ

application/json
model
enum<string>
デフォルト:grok-imagine-image
必須

Model ID. The quality variant delivers higher fidelity at a higher price

利用可能なオプション:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
必須

Prompt, English or Chinese. Describe subject, scene, style and lighting in detail

:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
integer
デフォルト:1

Number of images, 1-10. Values of 11 or above return 400; 0 is silently treated as 1

必須範囲: 1 <= x <= 10
:

1

aspect_ratio
enum<string>
デフォルト:1:1

Output aspect ratio. Actual pixel dimensions per resolution tier:

Values outside this enum do not raise an error — they silently fall back to 1:1.

利用可能なオプション:
1:1,
16:9,
9:16,
4:3,
3:4
:

"16:9"

resolution
enum<string>
デフォルト:1k

Resolution tier. 1k is roughly 0.9-1.05 megapixels and returns JPEG; 2k is roughly 4.2-4.5 megapixels and returns PNG (5-6 MB per image). Both tiers cost the same.

4k returns 503; other invalid values (such as 1K or 1024x1024) silently fall back to 1k.

利用可能なオプション:
1k,
2k
:

"1k"

response_format
enum<string>
デフォルト:url

Response format. url returns a direct image link (no signed query params); b64_json returns a raw base64 string (without the data: prefix).

Invalid values silently fall back to the default url.

利用可能なオプション:
url,
b64_json
:

"url"

レスポンス

Images generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n, regardless of actual prompt length. Use the Console billing records instead.